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:

Text
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:

Bash
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 Authorization header. 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:

ClientSends 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, ZedMCP requests only
ChatGPT and claude.ai connectorsNo 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.