MCP Gateway Authentication
Each client proves who it is before the gateway shows any tools. Pick the method by the client you have:
| Your client | Use | Each call acts as |
|---|---|---|
| Claude Code, Cursor, or another MCP client | OAuth: the client opens a browser for you | The person who signs in |
| A script or CI job | Platform token: one header | You or a service account |
| A client that already holds a token from your identity provider | Identity provider JWT: pass that token | The person in the token |
| A GitHub Actions workflow on a pull request | GitHub Actions: trade the job's GitHub token | The pull request's author, or whoever started the run |
| Your own app or service | OAuth client: the app gets its own identity | The 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.
- Copy the endpoint from the gateway's Connect tab into your client.
- Sign in to Archestra in the browser, and approve the client.
- 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.
Authorization: Bearer arch_<token>
| Token | Find it under | Calls act as |
|---|---|---|
| Personal Token | Your name in the sidebar | You, with your own server accounts |
| Service Account API Key | Settings → Service Accounts | The account, with its granted access |
| Legacy Team or Organization Token | Its migrated account in Settings → Service Accounts | The 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.
-
Add your OIDC provider under Settings → Identity Providers. See Identity Providers.
-
On the gateway, go to Advanced and pick that provider.
-
In your client, send the token the provider issued:
textAuthorization: Bearer <jwt> -
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:
-
On the gateway's Settings tab, turn on Accept GitHub Actions tokens under GitHub Actions.
-
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_claim, such asworkflow_ ref acme/review/.github/workflows/review.yml@refs/heads/main. A repository entryowner/*covers every repository of that owner, including new ones, so install the App on all of them. -
In the workflow, grant
id-token: write, request a GitHub OIDC token whose audience is yourARCHESTRA_, and send it:FRONTEND_ URL httpPOST <Archestra URL>/api/github-actions/token Content-Type: application/json {"token": "<GitHub OIDC token>", "resource": "<Archestra URL>/v1/mcp/<gateway id or slug>"} -
Check that the response holds an
access_for the gateway and atoken github_for the repository.token
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_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 inrequest 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:
error | Cause | Fix |
|---|---|---|
not_ | The gateway runs only as the author, and someone else started the run | The author starts a new run, or set Runs act as to Whoever started the run |
not_ | The person the run acts as has not connected GitHub through the App, or that connection expired or was revoked | They connect it under Credentials, then start the run again |
ambiguous_ | Several accounts connected the same GitHub user | Disconnect it from all but one account |
forbidden | The account of the person the run acts as cannot use the gateway | Share the gateway with them |
not_ | The repository, workflow, or event is not allowed, the pull request is from a fork, or the App cannot read it | Check the gateway's GitHub Actions settings and the App's installation |
invalid_ | The body lacks token or resource, or resource is not a gateway URL of this Archestra | Send both, with resource built from your Archestra URL |
invalid_ | Wrong audience, expired, or already exchanged | Request a new token with the right audience |
rate_ | Too many requests from one address | Wait for the time in the Retry-After header, then try again |
github_ | GitHub refused a request, for example because the App lacks one of the permissions above, or the App's private key cannot be used | Check the App's permissions, installation, and private key |
server_ | The exchange failed unexpectedly | Request 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.