MCP servers
An MCP Server Registration points your Organization at a Remote MCP Server that speaks Streamable HTTP, so Agents built on your Templates can call its tools. Registrations belong to the Organization. Your backend manages them with its Organization API Key at /api/v1/org/mcp/servers; an Organization owner can manage the same registrations through the Console API. User API Keys cannot manage or read them. See authentication.
Each registration’s authorization mode decides who holds its MCP Authorization, the credential its calls use: your Organization, once for every End User, or each End User, with their own account at the service.
Register a server
Section titled “Register a server”curl -X POST "$BASE_URL/api/v1/org/mcp/servers" \ -H "Authorization: Bearer $ORG_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"displayName":"Orders","endpointUrl":"https://tools.example.com/mcp","authorizationMode":"organization_static_token"}'displayName is unique in the Organization; endpointUrl is an HTTPS URL that several registrations may share, for example to use different credentials from different Templates. A registration is created enabled and needs no approval. authorizationMode decides what it sends to the server and who authorizes it:
| Mode | Sends | Authorized by |
|---|---|---|
none |
No credential. | Nobody: usable at once. |
organization_static_token |
One Organization token. | Your backend or an owner, setting the token. |
organization_client_credentials |
An access token Agent Service obtains with your OAuth client credentials. | Your backend or an owner, setting the credentials. |
organization_oauth |
An access token for one shared account at the service. | Someone who signs in with that account, through OAuth. |
end_user_static_token |
The token of the End User who owns the Session. | Your backend, for each End User. |
end_user_oauth |
An access token for the account of the End User who owns the Session. | Each End User, through OAuth in their browser. |
Every credential travels as Authorization: Bearer. Once an authorization is usable, the server’s tool catalog is discovered with its credential, so an End User’s catalog lists the tools that End User can use; in mode none the catalog is discovered when the registration is created. One authorization serves every Template and Session of its owner that references the registration.
In an Organization mode, reads return the registration’s authorization: its state (usable, invalid or revoked), invalidReason, requiredScope, hasCredential and catalog, whose toolNames lists the tools found. In an End User mode the registration’s authorization reads null, and the Organization’s …/authorization and refresh-catalog routes answer 409; your backend receives each End User’s authorization when it sets or confirms it, and the requirements read reports its status. Tokens, client secrets and OAuth tokens are write-only and never appear in reads, events or the model’s context. You may replace or revoke a credential at any time, also while Turns are using the registration; their next call uses the current one.
Organization credentials
Section titled “Organization credentials”organization_static_token:PUT /api/v1/org/mcp/servers/{serverId}/authorizationwith{"token": "..."}sets or replaces the token.organization_client_credentials: the samePUTwith{"clientId": "...", "clientSecret": "..."}sets or replaces the credentials. Agent Service reads the server’s401challenge and OAuth metadata, which name its authorization server, possibly on another host, and requests a token with theclient_credentialsgrant, for the scope the challenge names, otherwise the scopes the server advertises. A token that expires within a minute is renewed before the next call, so long Turns and Scheduler runs continue. When the authorization server rejects the request, the authorization readsinvalidwithinvalidReasontoken_rejecteduntil you set working credentials.
DELETE /api/v1/org/mcp/servers/{serverId}/authorization revokes the Organization’s authorization in any mode that holds one.
Authorize with OAuth
Section titled “Authorize with OAuth”In modes organization_oauth and end_user_oauth, the account holder signs in to the service on its own consent page, in a browser, and never gives their password to the platform. Agent Service is the OAuth client and keeps the tokens; your backend only starts the authorization and confirms who came back. Agent Service reads the server’s 401 challenge and OAuth metadata, and asks for the scope the challenge names, otherwise the scopes the server advertises, with PKCE, the server as resource and a single-use state. An access token that expires within a minute is refreshed before the next call; a refresh the authorization server rejects makes the authorization invalid with token_rejected until it is authorized again.
Revoking an authorization that holds OAuth tokens, in an OAuth or client credentials mode, also revokes them at the authorization server when the server offers revocation; a slow or failing server never delays the revocation here. Deleting a registration does the same for each of its authorizations.
The OAuth client
Section titled “The OAuth client”Agent Service presents the first of these clients to the authorization server:
- A client you registered with the service yourself, set on create or
PATCHas"oauthClient": {"clientId": "...", "clientSecret": "..."}. Add Agent Service’s callback,$BASE_URL/api/v1/mcp/oauth/callback, to its redirect URIs. Consent pages then show your client’s name, and reads return only itsclientId. - Agent Service’s Client ID Metadata Document, when the authorization server supports one. Its URL,
$BASE_URL/api/v1/mcp/oauth/client-metadata.json, is the client ID, so it needs an HTTPS address and changes with that address. - Otherwise a client Agent Service registers with the authorization server’s Dynamic Client Registration, once for the registration.
With the second or third, consent pages show the platform’s name, and you cannot set another; supply your own client to show yours. A client Agent Service obtained is kept while the authorization server still accepts it. Changing a registration’s client invalidates all its authorizations with client_changed, so tokens issued to one client never flow under another, and every owner authorizes again; a new clientSecret for the same clientId keeps them.
A start is refused with 409 mcp_oauth_unavailable and details.reason client_registration_unsupported when you set no client and the authorization server accepts neither a Client ID Metadata Document nor Dynamic Client Registration. It is refused with 502 mcp_oauth_unavailable when the server’s OAuth metadata cannot be read or lacks PKCE support, or when Dynamic Client Registration fails (client_registration_failed).
Allow return URLs
Section titled “Allow return URLs”After an authorization your backend started, the browser returns to a page of yours. Register those pages first: the Organization’s allowlist holds up to 20 absolute https URLs (http only on localhost, 127.0.0.1 or [::1]) without credentials, query or fragment. PUT replaces the list, GET reads it, and owners manage the same list through the Console API. The list is checked again when the browser comes back: an authorization started for a page you have since removed fails without returning to it, and holds nothing.
curl -X PUT "$BASE_URL/api/v1/org/mcp/oauth/return-urls" \ -H "Authorization: Bearer $ORG_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"returnUrls":["https://app.example.com/integrations/mcp/return"]}'Authorize End Users
Section titled “Authorize End Users”End User static tokens
Section titled “End User static tokens”If your backend already holds an End User’s token for the service, hand it over:
curl -X PUT "$BASE_URL/api/v1/org/users/$USER_ID/mcp/servers/$SERVER_ID/authorization" \ -H "Authorization: Bearer $ORG_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"token":"<end-user-token>"}'The response is that End User’s authorization, with owner.kind end_user. DELETE on the same path revokes an End User’s authorization in either End User mode; other End Users are unaffected. A userId that is not an ordinary End User of the Organization answers 404 resource_not_found, and a registration in another mode answers 409.
End User OAuth
Section titled “End User OAuth”Authorize an End User in four steps:
-
Start the authorization with a return URL whose origin and path match an allowlist entry; its query is yours and is kept. The response carries the
authorizationUrlto show the End User, valid untilexpiresAt, ten minutes ahead:Terminal window curl -X POST "$BASE_URL/api/v1/org/users/$USER_ID/mcp/servers/$SERVER_ID/authorization/oauth/start" \-H "Authorization: Bearer $ORG_API_KEY" \-H 'Content-Type: application/json' \-d '{"returnUrl":"https://app.example.com/integrations/mcp/return?state=<your-state>"}' -
The End User opens the link, signs in to the service and consents.
-
The service returns the browser to Agent Service, which redeems the code and holds the tokens. It then sends the browser to your return URL with
mcpOAuth=pending_confirmation,serverIdand a one-timeconfirmationvalue, or withmcpOAuth=failed,serverIdand areasonwhen the End User declined or the exchange failed. -
Your return page checks which End User is signed in to your application, and confirms the value for that End User:
Terminal window curl -X POST "$BASE_URL/api/v1/org/users/$USER_ID/mcp/servers/$SERVER_ID/authorization/oauth/confirm" \-H "Authorization: Bearer $ORG_API_KEY" \-H 'Content-Type: application/json' \-d '{"confirmation":"<confirmation>"}'The response is that End User’s
authorization, nowusable.
Confirmation is required because Agent Service cannot tell whose browser consented: anyone holding the link could sign in with their own account. Without it, a link forwarded to or intercepted by another person would bind that person’s account to your End User, and your End User’s Turns would act on it. Your application knows who is signed in when the browser comes back, and Agent Service accepts the value only for the End User the authorization was started for. Take the End User from your own sign-in, never from the return URL.
Nothing is usable before confirmation, and the tokens never leave Agent Service. A value works once, accepted or not, and lapses ten minutes after the callback. It is refused with 400 mcp_oauth_confirmation_invalid when it is unknown, used, lapsed, issued for another End User or registration, or the registration’s endpoint, mode or OAuth client changed since the start; start again. A confirmation replaces any token the End User held, and until then their current authorization stays as it was. When a result lapses unconfirmed, is refused, or is superseded by a later confirmation for the same End User, Agent Service also revokes its tokens at the authorization server, when the server offers revocation. A return URL outside the allowlist is refused with 400 validation_error and details.reason return_url_not_allowed.
Organization OAuth
Section titled “Organization OAuth”Mode organization_oauth holds one shared account. Your backend authorizes it with the same steps, without a userId: POST /api/v1/org/mcp/servers/{serverId}/authorization/oauth/start with {"returnUrl": "..."}, then /api/v1/org/mcp/servers/{serverId}/authorization/oauth/confirm with {"confirmation": "..."} once you have verified that the person who consented may authorize the shared account. An owner can also authorize it through the Console API; the callback then accepts only that owner’s browser session, so no confirmation follows.
Check what an End User needs
Section titled “Check what an End User needs”Before an End User’s first Turn, read what each referenced registration still needs, for a Template they may start a Session from or for a Session they own:
curl "$BASE_URL/api/v1/org/users/$USER_ID/agent-templates/$TEMPLATE_ID/mcp-authorization-requirements" \ -H "Authorization: Bearer $ORG_API_KEY"curl "$BASE_URL/api/v1/org/users/$USER_ID/sessions/$SESSION_ID/mcp-authorization-requirements" \ -H "Authorization: Bearer $ORG_API_KEY"The read uses the same local state as Turn admission, so ready is true exactly when no new Turn would be refused for MCP. For each registration, registrations reports its registrationStatus, authorizationMode, owner (organization or end_user), authorizationStatus (usable, missing, invalid, revoked or insufficient_scope) and satisfiedBy: end_user when the End User’s own token or OAuth authorization fixes it, organization when it needs your Organization’s credentials or enabling the registration, and null once it is ready. A Session may be created before its owner has authorized.
Change, disable and delete
Section titled “Change, disable and delete”| Method and path | Purpose |
|---|---|
GET /api/v1/org/mcp/servers |
List the Organization’s registrations. |
GET /api/v1/org/mcp/servers/{serverId} |
Read one registration. |
PATCH /api/v1/org/mcp/servers/{serverId} |
Change displayName, endpointUrl, authorizationMode or oauthClient, with the expectedServerVersion you read last. |
POST /api/v1/org/mcp/servers/{serverId}/disable |
Stop new Template saves, Session creation, new Turns and further calls that use it. |
POST /api/v1/org/mcp/servers/{serverId}/enable |
Allow them again. |
POST /api/v1/org/mcp/servers/{serverId}/refresh-catalog |
Discover the Organization authorization’s catalog again, with body {}. |
DELETE /api/v1/org/mcp/servers/{serverId} |
Delete a registration no non-archived Template references. |
Changing the endpoint or the mode invalidates every authorization of the registration with its catalog and revokes its credential, so a credential never reaches a different server; set new credentials or authorize again afterwards. Changing the display name does not. A refreshed catalog reaches Turns started afterwards. A delete removes the registration’s authorizations and destroys their stored credentials. While a Template references the registration, it answers 409 mcp_server_delete_blocked, and details.templates lists each templateId and templateName; remove the reference or archive the Template first. A Session that still references a deleted registration refuses new Turns with 409 session_execution_dependency_unavailable.
Use registrations in Templates
Section titled “Use registrations in Templates”Reference a registration from a Template’s content.tools.mcp as {"serverId": "<server-id>"}, and add "toolNames" to offer the model only some of its tools; see Templates. Two Templates may offer different tools of one registration, sharing its authorizations.
Every referenced registration is required by each new Turn. A disabled or deleted registration refuses the Turn with 409 session_execution_dependency_unavailable. A registration whose authorization for that Turn is not usable, because it was never set, was revoked or invalidated, or the server refused it, refuses the Turn before it starts with 409 mcp_authorization_required; details.registrations names each one with its serverId, owner and reason (missing, invalid, revoked or insufficient_scope). In an End User mode that is the authorization of the End User who owns the Session. A Backend Connection session.send reports the same code as its data.reason, and a Scheduler fire fails at once with it, without retrying.
When the server answers a call with HTTP 401 or 403, or the authorization is revoked while a Turn runs, the Turn ends failed with the same code and details instead of continuing without the server, and the authorization reads invalid with invalidReason unauthorized, forbidden or insufficient_scope (with the scope the server asked for in requiredScope). After insufficient_scope, the next OAuth authorization, or the client credentials set again, asks for the scope already granted together with requiredScope, so more access is granted only when a tool needs it; until that authorization completes, including its confirmation, the authorization keeps reading insufficient_scope. Set the credential again or authorize again, then start a new Turn; the conversation so far is kept.
Test Templates in the Console
Section titled “Test Templates in the Console”A Template Test in the Console calls the Template’s MCP servers as an End User’s Turn would. Registrations in an Organization mode use the Organization’s authorization. Registrations in an End User mode use the authorization of the Console owner’s own Template Test Identity, the hidden End User their Tests run as: the owner sets its static token, or authorizes it with OAuth, through the Console API, which the Console itself has no control for yet. The OAuth callback accepts only that owner’s browser session, so no confirmation step follows. The Console API also reads what a Test of the saved Template, or a follow-up Turn of a running Test, still needs. A Test whose authorization is not usable is refused with 409 mcp_authorization_required, and a refusal during a Test Turn ends that Turn as failed. Tests call no Connectors.
What the model sees
Section titled “What the model sees”The model calls each tool as mcp_<server>__<tool>, both parts derived from the server’s and the tool’s own names. A tool that does not conform, such as one with an oversized input schema or an invalid x-mcp-header declaration, is left out while the server’s other tools stay usable. Before each call only the called tool is compared with the catalog the Turn started with: a changed or removed tool fails that call with mcp_tool_changed or mcp_tool_removed, and the Turn continues. The server’s own instructions reach the model as untrusted reference.
A server that offers resources also gets platform__list_mcp_resources and platform__read_mcp_resource, which the model uses to bring documents into context. Images, audio and other binary results become Session files. Agent Service connects to servers of the 2026-07-28 protocol and of the earlier handshake-based revisions alike, and offers servers no Elicitation, Sampling or Roots: a call that needs them fails with its reason. Every request Agent Service makes to MCP and OAuth servers goes to public HTTPS addresses only.