Skip to main content

MCP protocol flows

This page describes what an MCP client and the gateway at POST /gateway/mcp send each other. Connect clients covers the setup for each client. This page is for building a client or reading a trace.

We checked the discovery responses and the method handling in Call tools on an instance. We have not run the sign-in steps by hand for this page.

Find the authorization server​

  1. The client calls POST /gateway/mcp with no token. Every method needs a token, initialize included. The answer is HTTP 401.

    HTTP/1.1 401
    WWW-Authenticate: Bearer resource_metadata="https://your-environment.example/.well-known/oauth-protected-resource"

    {"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"Authentication required"}}
  2. The client fetches the protected resource metadata (RFC 9728).

    {
    "resource": "https://your-environment.example/gateway/mcp",
    "authorization_servers": ["https://your-environment.example"],
    "bearer_methods_supported": ["header"],
    "scopes_supported": ["openid", "profile", "email", "mcp:tools", "mcp:resources", "read", "orderbook:read"]
    }

    scopes_supported lists the scopes in the cimd entry of the pbac.operator.controls.public_client_policy row (GatewayDiscoveryController.java). A connector or managed resource that is exposed over MCP adds its scopes there. A REST resource with no tool route adds none. With the resources from Register a managed resource, our instance listed orderbook:read from the MCP resource and no orders scope from the REST one. It also listed the scopes of the connectors installed on it.

  3. The client fetches /.well-known/oauth-authorization-server (RFC 8414) on the same origin. It names the endpoints, code_challenge_methods_supported: ["S256"], and registration_endpoint.

Sign in​

  1. The client registers itself at /register (RFC 7591), or uses a client id metadata document. The metadata sets client_id_metadata_document_supported to true.
  2. The client sends the user to /authorize with PKCE and code_challenge_method=S256. The server refuses plain. The resource parameter is <environment URL>/gateway/mcp, which the server maps to the type urn:mcp:server.
  3. The client exchanges the code at /token with the code verifier and the same resource.

Call tools​

MethodWhat the gateway does
initializeChecks only that a token is present. Answers with protocolVersion, capabilities: {"tools": {"listChanged": false}} and serverInfo.
tools/listLists every tool of every enabled resource, plus the two policyarc__ tools. It does not filter the list by the token's scopes. For each MCP resource it fetches the live list, which calls /introspect.
tools/callRuns the full gateway check for that one tool. See How the managed gateway works.
Any other methodJSON-RPC error -32601, Method not found.

On tools/call, an invalid or expired token is HTTP 401 with WWW-Authenticate: Bearer resource_metadata="...", error="invalid_token", so the client can refresh. A token that lacks the scope of the tool it calls gets a real HTTP 403 with a WWW-Authenticate challenge, error="insufficient_scope", and a JSON-RPC error body with code -32001. Its scope parameter lists the scopes the token already holds plus every scope of the connector being called. The client should sign in again requesting exactly that list, because the new token replaces the old one and asking for only the missing scope would drop the access the user already has. A DPoP-bound token gets the DPoP scheme instead of Bearer. If policy refuses a scope, the next call is challenged again, and the challenge text tells the user to ask an administrator. A policy denial is a normal tool result with "isError": true and the text HTTP 403: Access denied.

A connected client is not told when the tool list changes, because listChanged is false. Reconnect it to see new tools.

Connect another account​

We read this section in the code and did not run it. The bodies, the -32042 error and the /gateway/link refusal below are what the code builds, not responses we saw.

Some tools forward the user's own token from another identity provider, or a credential the user enters. If the user has not connected that account, or the stored token has expired and cannot be refreshed, the gateway returns a link instead of failing.

On /gateway/<name>/... the answer is HTTP 401 with this body.

{"error": "idp_link_required", "idp": "gitlab", "link_url": "https://your-environment.example/gateway/link?ls=..."}

On /gateway/mcp the answer depends on what the client declared in initialize.

  • A client that declared elicitation.url gets the JSON-RPC error -32042. Its data.elicitations[0] holds mode: "url", elicitationId, url and message.
  • Any other client gets a tool result with "isError": true, the link in the text, and _meta.idp_link_required with idp and link_url.

The link opens GET /gateway/link on the environment. The browser's PolicyArc session must belong to the same user the link was made for. With no session, the user signs in first. A session for a different user is refused with HTTP 403. After the user connects, the client retries the tool call.

For a tool that needs a credential the user enters, the error is user_secret_required, _meta holds user_secret_required, and the link opens the form at /gateway/connect.