MCPGateway Authentication

MCP Gateway Authentication

Each client proves who it is before the gateway shows any tools. Pick the method by the client you have:

Your clientUseEach call acts as
Claude Code, Cursor, or another MCP clientOAuth: the client opens a browser for youThe person who signs in
A script or CI jobPlatform token: one headerYou or a service account
A client that already holds a token from your identity providerIdentity provider JWT: pass that tokenThe person in the token
A GitHub Actions workflow on a pull requestGitHub Actions: trade the job's GitHub tokenThe pull request's author, or whoever started the run
Your own app or serviceOAuth client: the app gets its own identityThe app, or the person using it

Not sure? Use OAuth. It works with any MCP client. By default, you register nothing in Archestra first.

OAuth

Paste the gateway's URL into your client. It opens your browser, you sign in, and the tools appear. You register nothing in Archestra first. Each client signs in as the person, and gets only that person's tools.

  1. Copy the endpoint from the gateway's Connect tab into your client.
  2. Sign in to Archestra in the browser, and approve the client.
  3. Check that the client lists the gateway's tools.

A client registers itself in one of two ways. Archestra supports both, so any MCP client works:

  • Client ID Metadata Document: the client's ID is a URL that describes it. Newer clients use this.
  • Dynamic Client Registration: the client registers itself the first time it connects.

To allow only clients you register yourself, set ARCHESTRA_AUTH_DCR_ENABLED=false. That turns off both. Then register each client as an OAuth client.

Platform Token

For a script or a CI job: one header, no browser. The client gets the tools the token's owner can use.

text
Authorization: Bearer arch_<token>
TokenFind it underCalls act as
Personal TokenYour name in the sidebarYou, with your own server accounts
Service Account API KeySettings → Service AccountsThe account, with its granted access
Legacy Team or Organization TokenIts migrated account in Settings → Service AccountsThe service account created for that token

Use a service-account API key for automation; keep personal tokens for calls acting as you.

  • Keep a token secret. Anyone who has it acts as its owner. If a personal token leaks, click Rotate Token. For a service-account key, use Revoke API key, then Create API key, and update the clients that used it.
  • Legacy team and organization tokens keep their values when migrated to service accounts. A team token retains its team; an organization token receives an account without a team.
  • These accounts can use knowledge search when the gateway offers it and the account can access the sources. Migration does not grant access to every source.
  • For your own app, use an OAuth client instead. Its tokens expire, and you can limit what it reaches.

Identity Provider JWT

Already signed in to Okta or Entra ID? Send that token. Nobody needs an Archestra token. Use it for an internal app or agent platform that signs people in through your company's single sign-on. Identity providers are an Enterprise feature. See Pricing.

The call acts as the person in the token. So it can use their own server accounts, and Archestra can exchange their identity for a token each MCP server accepts.

  1. Add your OIDC provider under Settings → Identity Providers. See Identity Providers.

  2. On the gateway, go to Advanced and pick that provider.

  3. In your client, send the token the provider issued:

    text
    Authorization: Bearer <jwt>
    
  4. Check that the client lists the gateway's tools.

Archestra accepts the token only when:

  • It is genuine. The signature, issuer, and expiry check out against the provider's published keys.
  • It is for Archestra. Its audience is the provider's client ID in Archestra.
  • It names a known person. Its email matches an Archestra user who can use the gateway. If your provider puts the email in a custom claim, set Email Claim under the provider's Attribute Mapping.

Token rejected? Open the provider and go to Token Debugger. It shows the claims of your own latest sign-in, so you can see which claim holds the email.

GitHub Actions

A pull request workflow, such as an automated code review, can use the gateway as the pull request's author, or as whoever started the run, such as a maintainer who asked for a review. Its runs and costs count as that person's, and its review posts as your GitHub App. Nobody stores a token in GitHub: the job trades its own GitHub token for a gateway token.

Before you start:

  • A GitHub App credential for GitHub.com, installed on the repositories, with Pull requests write and Contents and Checks read. For reviews that resolve their own threads, give it Contents write.
  • A GitHub user credential that uses that App. Each person who starts runs connects it once: click your name in the sidebar, open Credentials, and click Connect.

Then:

  1. On the gateway's Settings tab, turn on Accept GitHub Actions tokens under GitHub Actions.

  2. Pick the App and whose account runs use under Runs act as. Turn on Resolve review threads to give each run's GitHub token Contents write, which GitHub requires to resolve a thread. Add the repositories, and add each trusted workflow as GitHub names it in the token's job_workflow_ref claim, such as acme/review/.github/workflows/review.yml@refs/heads/main. A repository entry owner/* covers every repository of that owner, including new ones, so install the App on all of them.

  3. In the workflow, grant id-token: write, request a GitHub OIDC token whose audience is your ARCHESTRA_FRONTEND_URL, and send it:

    http
    POST <Archestra URL>/api/github-actions/token
    Content-Type: application/json
    
    {"token": "<GitHub OIDC token>", "resource": "<Archestra URL>/v1/mcp/<gateway id or slug>"}
    
  4. Check that the response holds an access_token for the gateway and a github_token for the repository.

What to know:

  • The job that asks must come from a reusable workflow called at a branch, a tag, or a commit SHA. A workflow file in the pull request is never trusted, because the pull request can change it.
  • Only pull_request runs from the repository itself qualify, never a fork. With The pull request's author, only runs the author started qualify; a collaborator who pushes to someone else's pull request is refused. With Whoever started the run, the trusted workflow decides whose runs to start, so pick it only for a workflow that checks this. A re-run acts as the person who started the first run; the workflow can check who re-ran it in github.triggering_actor.
  • The gateway token lasts three hours. The GitHub token is limited to that one repository and lasts up to one hour.

A refusal names its reason in error:

errorCauseFix
not_authorThe gateway runs only as the author, and someone else started the runThe author starts a new run, or set Runs act as to Whoever started the run
not_linkedThe person the run acts as has not connected GitHub through the App, or that connection expired or was revokedThey connect it under Credentials, then start the run again
ambiguous_linkSeveral accounts connected the same GitHub userDisconnect it from all but one account
forbiddenThe account of the person the run acts as cannot use the gatewayShare the gateway with them
not_trustedThe repository, workflow, or event is not allowed, the pull request is from a fork, or the App cannot read itCheck the gateway's GitHub Actions settings and the App's installation
invalid_requestThe body lacks token or resource, or resource is not a gateway URL of this ArchestraSend both, with resource built from your Archestra URL
invalid_tokenWrong audience, expired, or already exchangedRequest a new token with the right audience
rate_limitedToo many requests from one addressWait for the time in the Retry-After header, then try again
github_errorGitHub refused a request, for example because the App lacks one of the permissions above, or the App's private key cannot be usedCheck the App's permissions, installation, and private key
server_errorThe exchange failed unexpectedlyRequest a fresh OIDC token and try again

ID-JAG

The gateway does not accept an ID-JAG yet. After accepting one, it would have to pass the person's identity on to each MCP server behind it, and no standard defines that step yet. The IETF Identity Continuation Assertion draft proposes one, and gateway support waits on it.

Archestra uses ID-JAG the other way today: it gets one from your identity provider to sign a person in to an MCP server. See ID-JAG.