Skip to content
AxecAxec Docs

Connect an MCP client

Use this guide when an MCP client should call Axec for a signed-in User. The resulting bearer has a User principal, is audience-bound to one gateway Resource, and carries only requested operation scopes such as mcp:invoke.

Prerequisites

Section titled “Prerequisites”
  • An active Application OAuth client and MCP gateway.
  • The exact gateway Resource, for example https://axec.example.com/g/release-copilot/mcp.
  • At least one active Connector attachment.
  • A registered redirect URI and an S256 PKCE-capable MCP client.

Connect

Section titled “Connect”
  1. Configure the MCP server URL as the exact gateway Resource.
  2. Let the client follow the gateway’s 401 challenge to its protected-resource metadata and then to the tenant authorization-server metadata.
  3. Register a public client through DCR if the client does not already have a registered client ID. DCR creates client identity; it does not create gateway authority.
  4. Start Authorization Code with S256 PKCE. Send the exact resource, the registered redirect URI, and mcp:invoke. Optionally repeat allowed_connector to narrow the Connector set; omitting it eagerly selects all active attachments.
  5. In the browser, sign in, connect any required upstream account, and accept the displayed authority.
  6. Redeem the one-use code with the same Resource, redirect URI, and PKCE verifier.

The client can now send independently authenticated Streamable HTTP POST requests. Axec does not require an Mcp-Session-Id:

POST /g/release-copilot/mcp
Authorization: Bearer <gateway-access-token>
Accept: application/json, text/event-stream
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18

Start with tools/list, then call only a returned <connector_key>__<capability_key> tool.

Verify

Section titled “Verify”

Confirm that the token audience equals the gateway Resource, the admitted GrantBundle belongs to the signed-in User, and tools/list exposes only capabilities allowed by current Grants and attachments. A later Grant, Connection, attachment, or credential restriction must block the next request even if the bearer has not expired.

Common failures

Section titled “Common failures”
  • invalid_target: the Resource does not exactly match the gateway.
  • invalid_scope: the client requested an unsupported operation scope.
  • Empty tools: the User has no currently usable Grant for an attached Connector.
  • Authorization returns to connection setup: the selected user-owned Connector has no active Connection.

For SDK-driven browser authorization, see Act on behalf of a User and Delegated User access.

Continue

Section titled “Continue”