Skip to main content

Call an MCP tool with an identity provider token

Enterprise Tier

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:

ItemValue in this example
Identity providerIssuer https://idp.example.com, signing keys at https://idp.example.com/.well-known/jwks.json
Organization (customer ID)acme
Projectpayments-assist
Catalog servercontext7, with the tools resolve-library-id and get-library-docs
Tool the profile exposesresolve-library-id
Profile ownerThe 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 oauth MCP 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.

  1. Create a gateway auth policy for the project on the gateway that serves it, with CreateGatewayAuthPolicy. A jwt policy 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"]
    }'
  2. Set the project's accepted credentials on that gateway to ACCEPTED_CREDENTIALS_TOKEN or ACCEPTED_CREDENTIALS_BOTH, with UpdateProjectGatewayProject. A project that accepts API keys alone, the default, gets no MCP route for its oauth profiles. Either value is accepted only while the project holds an enabled jwt policy 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"}'
  3. Create the profile as in the SaaS path below, with securityPolicyType set to oauth and no issuer or key set on the profile. An issuer or remote_jwks sent anyway is ignored while the project's policy exists. A securityPolicyValue that is set must be a JSON object, or the request is refused with INVALID_ARGUMENT.

Two refusals follow from these rules, each a failed_precondition:

  • No gateway auth policy for the project. Creating an oauth profile, switching a profile to oauth, or changing an oauth profile'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, or none. Spellings such as OAuth and oauth2 were 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 oauth profile 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:

CallAnswer
A valid token, and a tool the profile listsThe call reaches the MCP server
A tool the profile does not list400 invalid tool name, and the call never reaches the server
A missing, expired, wrong-issuer, or wrongly signed token401
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 key401

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.