Keys & auth

Every request to your endpoint carries a bearer key. The hub checks it at the edge, before anything reaches your box. If the key is wrong, missing, or revoked, the request stops there.

How a request is authenticated

A caller sends its key in the Authorization header:

POST https://your-slug.finchmcp.com/printer/mcp
Authorization: Bearer finch_...

The hub verifies the key, then strips the header before relaying the request to your box. Your local service never sees the caller's key, so it cannot leak it in logs, and it does not need any auth code of its own.

The hub stores only a hash of each key plus the last four characters for display. The full key exists in exactly one place: wherever you put it when it was shown at mint.

Mint a key

finch keys mint web-client --service printer
finch_k3y5h0wn0nc3...
# shown once. store it in the client now.

Every key needs a scope: --service <id> limits it to one service, --all lets it reach every service on the account. There is no unscoped default, you have to pick one.

List and revoke

finch keys list
  k_a1b2c3      web-client

finch keys revoke k_a1b2c3
finch: revoked key k_a1b2c3

Revocation is immediate. The next request with that key is rejected at the edge. finch keys list shows ids and labels, never the key itself. finch keys list and finch keys mint take --json for scripting.

Test with a key in the loop

Two commands exercise a service through the hub, so you can confirm the path works end to end:

finch test printer                          # list the service's MCP tools
finch call printer echo --args '{"text":"hi"}'   # invoke one tool

The CLI token is a different thing

A finch_ key lets a caller reach one service. The CLI token is a tenant-admin credential: it is what finch login saves on your box, and it can mint keys, add services, and revoke access. It lasts about 30 days.

finch token          # mint a fresh CLI token (e.g. to provision a new box)
finch revoke-tokens  # de-authorize every CLI login, including this box

finch token is how you enroll a second box without a browser: pipe its output into finch login --token - on the new machine (finch token | ssh newbox "finch login --token -"), or set FINCH_CLI_TOKEN there. Passing it as an argument works but puts a tenant-admin credential in the remote process table and shell history.

From the web, Settings → CLI access → Generate mints one and Copy puts a ready-to-run block on your clipboard — not a bare token. Paste the whole block on the box: it is finch login --token - with the token as a quoted heredoc, so the credential arrives on stdin and never becomes an argv word — argv is world-readable via /proc/<pid>/cmdline. Pasting it at an interactive prompt does still write it to your shell history (bash and zsh both save the full multi-line entry); prefix the paste with a space, or use the piped form below from a box that is already logged in, to keep it out of history as well. The same page revokes every CLI token at once.

finch login --hub https://finchmcp.com --token - <<'FINCH_CLI_TOKEN'
<your token>
FINCH_CLI_TOKEN

OAuth

MCP clients that speak OAuth can authenticate at the door without a raw key. The hub publishes standard protected-resource discovery metadata, so a client like Claude's custom connectors can run its own OAuth flow and present the resulting token instead of a finch_ key. For everything else, mint a key.