Service tokens and MCP
A service token lets a script, a scheduled job or an AI agent's MCP client reach an app without a browser sign-in. It travels in two request headers of its own.
Create one
Open LocalCan Access → Service tokens in the dashboard and select Create token. Give the token a name, choose the apps it reaches, and optionally pick the day it expires: it stops working at the end of that day, UTC. The dashboard shows the secret once: store it in your secret manager. The token's ID stays listed under its name. A team can have up to 50 tokens.
Send it
Every request carries both headers:
LC-Access-Client-Id: st_xxxxxxxxxxxx
LC-Access-Client-Secret: <the secret>
From a shell, keep the secret off the command line, where your shell history and the process list would keep it. Put both header lines in a file only you can read, and let curl read it:
chmod 600 lc-access-headers.txt
curl -H @lc-access-headers.txt https://metabase.example.com/api/health
- Except on a public path, a request with either header must carry a valid pair. A wrong, revoked or expired token gets 401 with the code
LC2004, and never falls back to sign-in. On a public path LocalCan ignores the token, so test a token on a path that isn't public. - LocalCan removes both headers before the request reaches your app, and sends no identity header with it.
- A revoked token is refused within 15 seconds. Its open WebSockets and event streams close within 30 seconds.
- Never put the secret in the
Authorizationheader. LocalCan doesn't read it there, your app may, and several MCP clients stop running their own OAuth sign-in when you set it.
MCP clients
An MCP client reaches an MCP server behind LocalCan Access with a service token when it sends the two headers on every request that needs them. Clients differ in which requests carry the custom headers you configure. As of November 2026:
| Client | Sends custom headers on |
|---|---|
| Claude Code (2.1.299 and later) | MCP requests and the OAuth requests: discovery, client registration and token |
| Codex (0.149 and later) | MCP requests and the OAuth requests to the MCP server's own address: discovery, client registration and token |
| VS Code, Gemini CLI, Zed | MCP requests only |
| ChatGPT and claude.ai connectors | No custom headers |
What that means for your MCP server:
- An MCP server with a fixed API key, such as Umami's
/mcp: a service token works with every client that sends custom headers. - An MCP server with its own OAuth sign-in, such as Metabase's: a service token alone works with Claude Code and Codex. The clients that send headers only on MCP requests also need the OAuth paths public, because their OAuth requests arrive without the token.
- Hosted connectors reach the MCP server only through public paths. The MCP server's own sign-in is then its only protection.
LocalCan tested Claude Code. The other rows come from each client's documentation and source code, and they change as the clients update, so check your client's release notes.
© 2026 LocalCan™. All rights reserved.