# Connect your agent

Point Claude Code, Claude, Codex or another MCP client at Hydrant, approve it in the browser and confirm it can read.

Hydrant doesn't run agents or supply a model. You bring the client; Hydrant gives it one workspace, a name in the history and rules it can't talk its way around. This page gets a client connected. It takes about two minutes, most of it your browser.

## Before you start

- You're a member of the workspace the agent should work in. Any role will do.
- An MCP client that speaks Streamable HTTP and OAuth. Claude Code, Claude (claude.ai or Desktop) and Codex are the ones we test. Codex needs **0.154.0 or newer**; 0.146.0 doesn't finish the sign-in on the way back.
- The address: `https://hydrant.dev/api/mcp`. The same steps, with the address filled in and a copy button, live in the app under **Settings › Agents › Connect your agent**.
- A free slot. Keys and browser connections share the workspace Owner's plan limit: 2 on Free, 20 on Solo Pro.

## Steps

### Claude Code

1. Add Hydrant. The default scope is this project, for you only. Add `--scope user` for every project you open, or `--scope project` to write a shared `.mcp.json` your teammates will see.

   ```bash
   claude mcp add --transport http hydrant https://hydrant.dev/api/mcp
   ```

2. Sign in. Inside Claude Code run `/mcp` and choose Authenticate, or from a shell:

   ```bash
   claude mcp login hydrant
   ```

   Over SSH, add `--no-browser` and open the printed link yourself.

3. Approve one workspace in the browser tab that opens. Your browser then returns to your own computer. That's the command line collecting its ticket, not a phishing attempt.

### Claude (claude.ai or Desktop)

1. Open **Customize › Connectors › Add custom connector** and paste `https://hydrant.dev/api/mcp` as the URL.
2. Choose **Connect**. A Hydrant tab opens: sign in and approve one workspace. Your browser goes back to claude.ai on its own.
3. Turn the connector on in a chat and ask for something in the workspace.

Custom connectors depend on your Claude plan. If the option isn't there, that's the plan, not you.

### Codex

1. Add Hydrant. The desktop app and IDE extension read the same configuration.

   ```bash
   codex mcp add hydrant --url https://hydrant.dev/api/mcp
   ```

2. Sign in. Codex opens the browser for you:

   ```bash
   codex mcp login hydrant
   ```

3. Approve one workspace in the browser tab that opens.

### Another MCP client

1. Give it `https://hydrant.dev/api/mcp`. It needs Streamable HTTP and OAuth, with either client ID metadata documents or dynamic registration.
2. When it opens a browser, sign in and approve one workspace.
3. Have it read the workspace.

If the client can't do OAuth at all, use [an agent key](/help/agents/agent-keys) instead.

## What you should see

- **Claude Code:** `claude mcp list` says Connected. "Needs authentication" means step 2 again.
- **Codex:** `codex mcp list`, or `/mcp` inside Codex, shows hydrant as authenticated.
- **Everywhere:** the connection appears under **Settings › Agents › Connections**. It starts as "authorized, waiting for its first contact" and flips to "verified" after the agent's first request. A green dot in your client is your client's opinion. [Verified is the proof](/help/agents/first-read).

## Optional: the Hydrant skill

`npx skills add Background-Craft/hydrant-skills` teaches Claude Code and Codex how work moves here. Connecting doesn't need it. Working well does. It needs Node.js; `npx` comes with it.

## If it goes sideways

- **The browser said "Nothing to approve."** The request went stale. Start again from your client.
- **"That account isn't a member here."** You signed in with a GitHub account that isn't in the workspace. Ask an Admin for an invitation, then try again. [Who can do what](/help/using/views-and-settings#who-can-do-what).
- **It connected to the wrong workspace.** One connection, one workspace. Revoke it under Connections and connect again, picking the right one this time.
- **To start over:** `claude mcp remove hydrant` or `codex mcp remove hydrant`, then step 1 again. Other servers in your configuration are not touched.
- **Everything else:** [Troubleshooting](/help/agents/troubleshooting).

Contact: bots@hydrant.dev