MCP servers
List MCP servers
Newest first, without their tools.
Required scope: actions:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List MCP servers › Responses
objecthasMorenextCursorConnect an MCP server
Connects a Streamable HTTP MCP server and asks it for its tools right away. The URL must be public and its site must be allowed for this key, the same list actions use. The connection is made to the address that was checked and redirects are not followed, so a server that redirects to an internal address is rejected. If the server does not answer, nothing is saved and the answer is 422 mcp_server_unreachable. Grant its tools to agents with PUT /v2/agents/{id}/tools/{toolId}.
Required scope: actions:write.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Connect an MCP server › Request Body
nameHow you see it. Its lowercase form prefixes every tool name the agent sees, so it cannot repeat or start like another server.
urlA public http or https URL of a Streamable HTTP MCP server. It never comes back in a response, only its origin. Redirects are not followed.
Defaults to none. OAuth servers are connected from the dashboard.
noPersistWhen true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn.
sharedWithSubaccountsPlatforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents.
Connect an MCP server › Responses
objectidnameoriginOnly the origin. The path and query may hold a secret.
statusconnected: the last discovery worked, the last tool call was answered and its tools can be granted. error: the last discovery or the last tool call failed; lastError says which. inactive: not connected.
authTypetoolCountnoPersistWhen true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn.
sharedWithSubaccountsPlatforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents.
lastErrorlastDiscoveryAtcreatedAtupdatedAtWhat the last discovery found.
sharedByPlatformTrue when your platform shares this server with you: you can grant its tools, not change it. Absent on your own servers.
Retrieve an MCP server
Includes the tools found by the last discovery.
Required scope: actions:read.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve an MCP server › Responses
objectidnameoriginOnly the origin. The path and query may hold a secret.
statusconnected: the last discovery worked, the last tool call was answered and its tools can be granted. error: the last discovery or the last tool call failed; lastError says which. inactive: not connected.
authTypetoolCountnoPersistWhen true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn.
sharedWithSubaccountsPlatforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents.
lastErrorlastDiscoveryAtcreatedAtupdatedAtWhat the last discovery found.
sharedByPlatformTrue when your platform shares this server with you: you can grant its tools, not change it. Absent on your own servers.
Disconnect an MCP server
Removes its tools from every agent that had them, then disconnects the server.
Required scope: actions:write.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Disconnect an MCP server › Responses
Disconnected.
Update an MCP server
Changes only what you send. A new url or auth discovers the tools again; if that fails the server stays with status error. Servers connected by OAuth are reconnected from the dashboard.
Required scope: actions:write.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Update an MCP server › Request Body optional
nameurlChanging it discovers the tools again.
Replaces the credentials and discovers the tools again.
noPersistWhen true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn.
sharedWithSubaccountsPlatforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents.
Update an MCP server › Responses
objectidnameoriginOnly the origin. The path and query may hold a secret.
statusconnected: the last discovery worked, the last tool call was answered and its tools can be granted. error: the last discovery or the last tool call failed; lastError says which. inactive: not connected.
authTypetoolCountnoPersistWhen true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn.
sharedWithSubaccountsPlatforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents.
lastErrorlastDiscoveryAtcreatedAtupdatedAtWhat the last discovery found.
sharedByPlatformTrue when your platform shares this server with you: you can grant its tools, not change it. Absent on your own servers.
List the tools of an MCP server
The tools found by the last discovery, as a list. Use it to get the id that PUT /v2/agents/{id}/tools/{toolId} takes. It reads what is stored and does not call the server: to refresh it, call POST /v2/mcp-servers/{id}/discover.
Required scope: actions:read.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List the tools of an MCP server › Responses
objecthasMorenextCursorDiscover tools
Asks the server for its tools now and returns the server (not a list) with its tools in the tools field; use GET /v2/mcp-servers/{id}/tools for a paginated list. It calls the server, so it is not free to repeat: an organization can discover at most 20 times per minute, and the next call answers 429 rate_limited with Retry-After. It is safe to retry. Answers 422 mcp_server_unreachable when the server does not answer (the server is marked error until a discovery works).
Required scope: actions:write.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Discover tools › Responses
objectidnameoriginOnly the origin. The path and query may hold a secret.
statusconnected: the last discovery worked, the last tool call was answered and its tools can be granted. error: the last discovery or the last tool call failed; lastError says which. inactive: not connected.
authTypetoolCountnoPersistWhen true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn.
sharedWithSubaccountsPlatforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents.
lastErrorlastDiscoveryAtcreatedAtupdatedAtWhat the last discovery found.
sharedByPlatformTrue when your platform shares this server with you: you can grant its tools, not change it. Absent on your own servers.
Read the run identity of an MCP server
Use it to know whether Lelemon signs its calls to this server and with which header, audience and secret id (kid). It never returns the secret. When enabled is false the calls go unsigned and your server gets no verified user or case context.
Required scope: actions:read.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Read the run identity of an MCP server › Responses
objectserverIdenabledTrue when Lelemon signs every call it makes to this server. False means calls go unsigned and the server gets no verified context.
headeraudiencekidThe kid of the secret that signs now. The JWT header carries it, so your server picks the right secret during a rotation.
secretCreatedAtTurn on or rotate the run identity of an MCP server
Use it so your MCP server can trust who is asking: from now on every tools/call carries a JWT (HS256, 60 seconds) in the header, with the user, case, contact and tool in its claims; verify it with the SDK (verifyMcpAssertion). If the identity is already on, it issues a new secret and the previous one keeps verifying until the next rotation, so accept both by kid. The secret is shown once, in this answer. It changes how the server is called, so it is not idempotent and ignores Idempotency-Key. Use dryRun=true to check the header and audience and see whether it would rotate; nothing is saved.
Required scope: actions:write.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Turn on or rotate the run identity of an MCP server › Request Body optional
header^[a-z][a-z0-9-]{2,63…Header that carries the signed JWT. Lowercase letters, digits and hyphens, 3 to 64 characters, not one the server already uses for its own auth. Default x-agente-corrida.
audience^\S+$The aud claim: an https URL or an identifier without spaces, up to 200 characters. Default the URL of the server without query or fragment.
Turn on or rotate the run identity of an MCP server › Responses
objectserverIdenabledTrue when Lelemon signs every call it makes to this server. False means calls go unsigned and the server gets no verified context.
headeraudiencekidThe kid of the secret that signs now. The JWT header carries it, so your server picks the right secret during a rotation.
secretCreatedAtsecretHS256 secret. Shown only in the answer that creates it, never again, and absent in a dryRun. Store it now.
rotatedOnly in the answer to POST: true when the identity was already on and this call replaced the signing secret. The previous secret keeps verifying until the next rotation, so your server accepts both for a while.
dryRunPresent and true when the request had dryRun=true.
Turn off the run identity of an MCP server
Lelemon stops signing its calls and forgets the secrets. Do it only after your server stops requiring the JWT, or its calls will be rejected. Safe to repeat.
Required scope: actions:write.
path Parameters
id^mcp_[0-9A-Za-z]{22}… · requiredThe id of the mcp server (mcp_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Turn off the run identity of an MCP server › Responses
Turned off.