Agent keys

Browser sign-in is the better door: it expires and no secret passes through your hands. Some clients can’t use it. For those there are keys.

A key skips the browser: no sign-in, no expiry, and revoked only by a person. You choose read only or read and write when you create it. Anyone holding the key has that access as you, in that workspace, until someone revokes it. Treat it like a house key you can’t re-cut.

Before you start

• You’re a member of the workspace. A key stays capped by your current role and dies permanently if you leave.
• A free slot. Keys and browser connections share one limit per workspace, set by the Owner’s plan: 2 on Free, 20 on Solo Pro, no cap on Team. Unavailable entries count until they’re revoked. Plans and billing.
• Somewhere private to put a secret. Not a chat, not a screenshot, not a repository.
• Hydrant allows 5 new keys per person per hour. You shouldn’t need a sixth.

Steps

Create the key

1. Open Settings › Agents and find Access. It always sits below Named agents.
2. Press Create agent key beside the Access heading. Enter a Key name that says which client and whose machine. Under Access, keep the Read and write default or choose Read only, then press Create key.
3. Copy it now. “Your key is ready” means exactly once: leaving the page or pressing Dismiss key clears the only copy. Press Copy key and store it privately. Show key reveals it if you need to check it. The MCP address to go with it sits right below.

Try to leave before copying and Hydrant asks “Copied the key?” first. Stay and copy is the right answer.

Give it to the client

Pass the key as an environment variable, never as a URL parameter.

Claude Code. Put the key in a shell variable first, so it isn’t typed into the command below. read -s HYDRANT_KEY (paste, then Return) keeps it out of your shell history; a plain export HYDRANT_KEY=… works too, but that line lands in history itself. Then:

claude mcp add --transport http hydrant https://hydrant.dev/api/mcp --header "Authorization: Bearer ${HYDRANT_KEY}"

Claude Code keeps the value in its own configuration. Treat that file like the key.

Codex. In ~/.codex/config.toml, give the hydrant server bearer_token_env_var = "HYDRANT_KEY" and export that variable with your key. Keep the key out of the file itself.

Anything else. Send Authorization: Bearer followed by the key on every request to https://hydrant.dev/api/mcp.

Claude’s custom connectors (claude.ai and Desktop) don’t take a key. Use browser sign-in there.

What you should see

The key appears in the Access list as active, with its saved access and creation time. Everything it does is recorded under the key’s name and yours, like Build laptop (agent; via Sam Rivera). To show a named agent’s name and face on that work instead, pick one under Shown as on the key’s row. See Named agents.

Members see their own keys. Admins and the Owner see everyone’s.

State	Means
active	Works.
pending	Creation didn’t confirm. The secret, if one was made, can’t be shown again. Revoke it.
unavailable	It no longer authenticates. Revoke it to free its slot.
revoked	Dead, and moved to the collapsed Revoked group for the record.

If it goes sideways

• You left the page before copying. The secret is gone for good. Revoke that entry and create a replacement.
• The creation didn’t confirm. The button changes to Retry creation, which repeats the same request safely. If you’d rather start fresh, Start another creation, then revoke the uncertain entry.
• “This creation was already attempted.” A retry reached Hydrant after the first attempt had already made a key. Refresh the list, revoke that entry and create a new one. Its secret can’t be shown again.
• “Agent key creation is limited to 5 keys per hour.” The message says how long to wait. Wait that long.
• 401 and “Agent credential is unavailable.” The key is wrong, revoked, or the person who created it left the workspace. Check the list; create a new key if needed.
• insufficient_scope on a write. This is a read-only key. Revoke it and create a read-and-write replacement if the client needs to change workspace data.
• “Free allows 2 agent connections per workspace…” Every slot is taken. Revoke what you don’t use first.
• It leaked. Press Revoke, then Revoke key. Now, not after lunch. History made with it stays intact and attributed. Then work out how it leaked.