Call an MCP tool with an identity provider token
An application can call a Model Context Protocol (MCP) tool with a token from the organization's own identity provider, and the token stays at the gateway. This guide sets up the oauth MCP profile that makes this possible, with every step a management API call.
How it works
An application obtains a token from the identity provider, connects to the profile's address, and presents the token. The gateway checks it against the issuer named on the profile and admits the call to the tools the profile lists. Step 5 lists what the gateway answers.
The caller's token is never passed on to the MCP server. The server receives the credential stored for it in the profile, if there is one, and otherwise no Authorization header.
Where the profile names its identity provider depends on the install. On a self-hosted install, from 0.12.0, the profile takes the issuer, keys, audiences, and required scopes from its project's gateway auth policy. On SaaS, the profile carries its own issuer and key set.
The example
One project, payments-assist, exposes the documentation search of one catalog server to an application. The values used throughout:
| Item | Value in this example |
|---|---|
| Identity provider | Issuer https://idp.example.com, signing keys at https://idp.example.com/.well-known/jwks.json |
| Organization (customer ID) | acme |
| Project | payments-assist |
| Catalog server | context7, with the tools resolve-library-id and get-library-docs |
| Tool the profile exposes | resolve-library-id |
| Profile owner | The user whose ID is ${USER_ID} |
| Project gateway (self-hosted) | The gateway that serves payments-assist, with the ID ${PROJECT_GATEWAY_ID} |
| Token audience and scope (self-hosted) | Audience payments-mcp, required scope mcp.tools |
The management API calls use ${MANAGEMENT_URL} for the management API address and ${ADMIN_API_KEY} for a management key, sent as a Bearer token.
Prerequisites
- The management plane and every data plane serving the project run 0.11.0 or later. The rules below are 0.11.0 behavior. On a self-hosted install, the data planes serving the project run 0.12.0 or later, because a data plane older than 0.12.0 receives no
oauthMCP profiles from a 0.12 management plane. - The project exists and is served by a data plane. See Serve a project from a data plane.
- The identity provider serves its key set from an absolute http or https address, and can issue a token for the application's client.
- The catalog server exists. See Govern MCP server access.
Step 1: grant the server to the project
A profile can attach only a server that its project has been granted. Without the grant, attaching the server is refused with 403 permission_denied and the detail server is not allowed for this project.
curl -sS -X POST "${MANAGEMENT_URL}/admin/v1/customers/acme/projects/payments-assist/mcp-servers" \
-H "Authorization: Bearer ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"serverId": "context7"}'
The response carries the grant:
{
"entry": {
"id": "<grant-id>",
"customerId": "acme",
"projectId": "payments-assist",
"serverId": "context7",
"createdAt": "2026-11-06T10:38:09.332183Z"
}
}
Step 2: create the profile with the identity provider
The identity provider is named in a different place on a self-hosted install and on SaaS. Each path ends with a profile of type oauth in the pending state, as shown at the end of the SaaS path.
On a self-hosted install
From 0.12.0 an oauth profile does not hold an issuer or key set. It uses the project's gateway auth policy, which also sets the audiences and the scopes a token must carry. The policy and the project's accepted credentials are set before the profile is created.
-
Create a gateway auth policy for the project on the gateway that serves it, with
CreateGatewayAuthPolicy. Ajwtpolicy names at least one audience, and the gateway takes at most one enabled policy per issuer. The policy fields are described in The set of trusted issuers.curl -sS -X POST "${MANAGEMENT_URL}/admin/v1/gateway-auth-policies" \-H "Authorization: Bearer ${ADMIN_API_KEY}" \-H "Content-Type: application/json" \-d '{"customerId": "acme","projectId": "payments-assist","projectGatewayId": "'"${PROJECT_GATEWAY_ID}"'","name": "payments-idp","mechanism": "jwt","issuer": "https://idp.example.com","jwksUri": "https://idp.example.com/.well-known/jwks.json","audiences": ["payments-mcp"],"requiredScopes": ["mcp.tools"]}' -
Set the project's accepted credentials on that gateway to
ACCEPTED_CREDENTIALS_TOKENorACCEPTED_CREDENTIALS_BOTH, withUpdateProjectGatewayProject. A project that accepts API keys alone, the default, gets no MCP route for itsoauthprofiles. Either value is accepted only while the project holds an enabledjwtpolicy on that gateway.curl -sS -X PATCH "${MANAGEMENT_URL}/admin/v1/project-gateways/${PROJECT_GATEWAY_ID}/projects/payments-assist" \-H "Authorization: Bearer ${ADMIN_API_KEY}" \-H "Content-Type: application/json" \-d '{"acceptedCredentials": "ACCEPTED_CREDENTIALS_BOTH"}' -
Create the profile as in the SaaS path below, with
securityPolicyTypeset tooauthand no issuer or key set on the profile. Anissuerorremote_jwkssent anyway is ignored while the project's policy exists. AsecurityPolicyValuethat is set must be a JSON object, or the request is refused withINVALID_ARGUMENT.
Two refusals follow from these rules, each a failed_precondition:
- No gateway auth policy for the project. Creating an
oauthprofile, switching a profile tooauth, or changing anoauthprofile's settings in a project with no gateway auth policy is refused with "set up a gateway auth policy for the project first". - A project that accepts API keys alone on every gateway where it has a policy. The profile would never be served, so the write is refused. A rename or a description edit still works. Setting the accepted credentials, as in the second step, resolves it.
A profile is never sent to a gateway on which its project has more than one policy, or one that cannot be used, such as a policy with no audience. Each such project needs exactly one usable policy on that gateway. A profile saved before 0.12.0 with its own issuer and key set keeps working in 0.12, with any audience and a warning, while MCP_OAUTH_STRICT_PROFILES is off. See Profiles saved before 0.11.0.
On SaaS
A profile of type oauth names its identity provider in security_policy_value: the issuer, and remote_jwks, the address of the provider's key set as an absolute http or https URL. The value is a JSON string.
curl -sS -X POST "${MANAGEMENT_URL}/v1/customers/acme/projects/payments-assist/users/${USER_ID}/mcp-profiles" \
-H "Authorization: Bearer ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "payments-docs",
"description": "Documentation search for the payments assistant.",
"securityPolicyType": "oauth",
"securityPolicyValue": "{\"issuer\":\"https://idp.example.com\",\"remote_jwks\":\"https://idp.example.com/.well-known/jwks.json\"}"
}'
The profile is created with the status pending, and with an empty endpoints list until a data plane serves it:
{
"id": "<profile-id>",
"user_id": "<user-id>",
"customer_id": "acme",
"project_id": "payments-assist",
"name": "payments-docs",
"description": "Documentation search for the payments assistant.",
"url": "/mcp/<path-assigned-by-the-server>",
"endpoints": [],
"status": "pending",
"error_message": "",
"security_policy_type": "oauth",
"security_policy_value": "{\"issuer\":\"https://idp.example.com\",\"remote_jwks\":\"https://idp.example.com/.well-known/jwks.json\"}",
"servers": []
}
Three refusals follow from the 0.11.0 rules. Each is a 400 invalid_argument, and the response bodies below show the fields that matter:
-
A security type other than
oauth,api_key, ornone. Spellings such asOAuthandoauth2were accepted before 0.11.0 and served with no token check.{"title": "invalid_argument","status": 400,"detail": "security_policy_type must be one of oauth, api_key or none","reason": "INVALID_ARGUMENT"} -
An
oauthprofile with no issuer or key set address.{"title": "invalid_argument","status": 400,"detail": "security_policy_value.issuer is required for an oauth profile","reason": "INVALID_ARGUMENT"} -
An update that changes the type to
oauth, the issuer, or the key set address and leaves either missing or invalid. An update that changes none of them is accepted, so a profile saved without them can still be renamed.
Step 3: attach the server with the tools it exposes
On an oauth profile, each server lists 1 to 32 distinct tool names or regex: patterns, and regex:* means every tool. An empty list is refused (the responses in this step show the fields that matter):
curl -sS -X POST "${MANAGEMENT_URL}/v1/customers/acme/projects/payments-assist/users/${USER_ID}/mcp-profiles/${PROFILE_ID}/servers" \
-H "Authorization: Bearer ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"serverId": "context7", "tools": []}'
{
"title": "invalid_argument",
"status": 400,
"detail": "tools must list at least one tool name for an oauth profile",
"reason": "INVALID_ARGUMENT"
}
Listing the tool exposes only that tool:
curl -sS -X POST "${MANAGEMENT_URL}/v1/customers/acme/projects/payments-assist/users/${USER_ID}/mcp-profiles/${PROFILE_ID}/servers" \
-H "Authorization: Bearer ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"serverId": "context7", "tools": ["resolve-library-id"]}'
{
"server_id": "context7",
"status": "active",
"enabled_tools": ["resolve-library-id"],
"has_credential": false,
"created_at": "2026-11-06T10:38:14.813398Z"
}
Blank, padded, and repeated entries are refused as well. Sending the list a server already has is accepted, so a server's token can be rotated. The same rule applies to the CLI: tetrate agentrouter api mcp profiles servers add and servers set-tools both need --tools on an oauth profile.
Step 4: wait until the profile is served
A new profile stays pending until the data plane has accepted the route for its path. A profile with no servers, or one refused under strict OAuth settings, has no route and stays pending. The endpoints list fills in as soon as a data plane serving the project reports an address, with an absolute url and the projectGatewayId of the serving gateway. An empty list means no data plane serving the project reports an address yet. A client connects once the status is active, to the address as the profile returns it, and not to one joined onto a host by hand. See Aggregate MCP servers into a profile.
Repeat the read until the status is active:
curl -sS "${MANAGEMENT_URL}/v1/customers/acme/projects/payments-assist/users/${USER_ID}/mcp-profiles/${PROFILE_ID}" \
-H "Authorization: Bearer ${ADMIN_API_KEY}" | jq -r .status
active
The address to connect to is endpoints[0].url of the same response. Envoy can take a few more seconds to serve a route that has just turned active, so a first call can still answer 404, 403, or 503. Repeating it every 5 seconds for up to 90 seconds covers that.
Step 5: connect with a token from the identity provider
The application gets a token from the identity provider with the client-credentials grant, then connects to the profile's address with the token as a Bearer value. The gateway answers as follows:
| Call | Answer |
|---|---|
| A valid token, and a tool the profile lists | The call reaches the MCP server |
| A tool the profile does not list | 400 invalid tool name, and the call never reaches the server |
| A missing, expired, wrong-issuer, or wrongly signed token | 401 |
| A token issued for another audience, or missing a scope the policy requires (self-hosted, from 0.12.0) | 403, and the call never reaches the MCP server |
| An Agent Router API key | 401 |
The protocol handshake opens a session, and the session identifier is returned in the mcp-session-id response header. PROFILE_URL is the profile's address from Step 4, and TOKEN is the access token:
export MCP_PROTOCOL_VERSION=2025-06-18
curl -sS -D - -X POST "${PROFILE_URL}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "MCP-Protocol-Version: ${MCP_PROTOCOL_VERSION}" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"'"${MCP_PROTOCOL_VERSION}"'","capabilities":{},"clientInfo":{"name":"payments-assist","version":"0"}}}'
A 200 answers the handshake. The later calls carry mcp-session-id: ${SID}, where SID is the value of that header. Tools are listed as the server ID, two underscores, and the tool name, so the profile in this example lists context7__resolve-library-id:
curl -sS -X POST "${PROFILE_URL}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "MCP-Protocol-Version: ${MCP_PROTOCOL_VERSION}" \
-H "mcp-session-id: ${SID}" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"context7__resolve-library-id","arguments":{"libraryName":"react"}}}'
The call answers 200 with the tool's result. A tools/list request, with the same headers and "method":"tools/list", returns the one listed tool.
Profiles saved before 0.11.0
A profile saved before 0.11.0 with an empty tool list, or with no issuer, is still served on a 0.11 data plane, with a warning, and on a 0.12 data plane, where MCP_OAUTH_STRICT_PROFILES is off by default. The setting turns on by default in 0.13. Under it, a server with an empty tool list is left out, and a profile with no issuer or no server left is not served. See Upgrade the data plane for how to find the affected profiles and to try the strict behavior early.
Where to go next