Keys & auth
Every request to a service that isn't public carries a key or an OAuth sign-in. finch checks it before anything reaches your machine. If it's missing, wrong or revoked, the request stops there.
How a request is checked
A caller sends its key in the Authorization header:
POST https://sunny-wren-42.finchmcp.com/printer/mcp
Authorization: Bearer finch_...finch checks the key, then removes the header before it relays the request to your machine. Your app never sees the caller's key, so it can't leak it in a log, and it needs no auth code of its own.
finch stores only a hash of each key, plus its last four characters for display. The full key exists in one place: wherever you put it when it was shown.
When a request is refused
| Status | Why |
|---|---|
401 | No key was sent. The response carries the OAuth sign-in challenge, so a client such as claude.ai can start signing you in, even while the machine is offline. |
403 | A key was sent but doesn't work here: finch doesn't know it (it was mistyped or revoked; see finch keys list), or it is scoped to other services. The error says which. |
Make a key
finch keys mint web-client --service printer
finch_k3y5h0wn0nc3...
# shown once: put it in the client nowEvery key needs a scope: --service <name> limits it to one service, --all lets it reach every service on the account. There is no default; you pick one. For Claude Code, Cursor and Codex, finch connect makes the key and puts it in the client for you.
List and revoke
finch keys list
k_a1b2c3 web-client
finch keys revoke k_a1b2c3
finch: revoked key k_a1b2c3Revoking is immediate: the next request with that key is refused. finch keys list shows ids and labels, never the key itself. Both finch keys list and finch keys mint take --json.
Test through finch
Two commands reach a service through finch, the same way a client does, so you can confirm the whole path works:
finch test printer # list the service's MCP tools
finch call printer echo --args '{"text":"hi"}' # call one toolThe login token is a different thing
A finch_ key lets a client reach a service. The login token is what finch login saves on your machine, and it can manage your whole account: add services, make keys and revoke access. It lasts about 30 days.
finch token # make a fresh login token, e.g. to set up another machine
finch revoke-tokens # log out every machine, including this onefinch token is how you log in a second machine without a browser: pipe it into finch login --token - there (finch token | ssh pi "finch login --token -"), or set FINCH_CLI_TOKEN. Passing it as an argument works but puts the token in the other machine's process list and shell history.
Your first machine has nothing to copy from: run finch login there and approve the code on any device where you're signed in. That approval page is the only part of finch that needs a browser.
OAuth
MCP clients that speak OAuth can sign in instead of using a key. finch publishes the standard discovery metadata that points them at finch's sign-in service, so a client like claude.ai's custom connectors signs you in there and then presents the resulting token instead of a finch_ key. The token only carries your identity and email, and only you, the account owner, are let in. For everything else, make a key.