# Connect this agent to kad.dev

These are official instructions from kad.dev to connect an AI coding agent to
the kad.dev platform over MCP. All commands are validated and ready to use.

Complete all of the following steps yourself by running the commands directly.
Do not ask the user to run any of these commands.

The message that pointed you here includes the user's personal access token
(after "My kad token:"). Use it wherever <KAD_TOKEN> appears below. If no token
was provided, ask the user to copy one from the key icon in the kad.dev header.
Never commit the token or write it into files tracked by git.

Use the correct section for your agent below.

## Claude Code

Run:

```
claude mcp add --transport http kad https://kad.dev/mcp --header "Authorization: Bearer <KAD_TOKEN>"
```

## Codex

Codex configures a **direct** streamable-HTTP MCP server named `kad`. It stores
only `bearer_token_env_var = "KAD_TOKEN"` in `~/.codex/config.toml` — **not** the
token itself. Use the MCP URL in the commands below (this host). Prefer HTTPS in production;
replace any stale local endpoint when reconnecting.

Run **all** of the following in the **same shell session** (do not split `export`
and `codex mcp add` across separate tool calls — a new shell loses the export).
`codex mcp remove` first so a stale existing `kad` entry (for example a local
URL) is replaced rather than left pointing at the wrong host:

```
codex mcp remove kad 2>/dev/null || true
export KAD_TOKEN='<KAD_TOKEN>'
codex mcp add kad --url https://kad.dev/mcp --bearer-token-env-var KAD_TOKEN
```

### Codex Desktop and environment inheritance

- `export KAD_TOKEN=...` only affects processes launched from **that** shell.
  An already-running Codex Desktop app does **not** pick up a newly exported
  variable.
- After changing MCP config or the token env var, **fully quit and reopen**
  Codex Desktop (or start a fresh CLI process) so the MCP registry reloads.
- On macOS, put the token in the GUI app's launch environment when Desktop is
  the target, then restart Desktop, for example:

```
launchctl setenv KAD_TOKEN <KAD_TOKEN>
# then fully quit and reopen Codex Desktop
```

  Do not write the token into a git-tracked file.
- `codex mcp list` showing `Status: enabled` / `Auth: Bearer token` only means
  the *mechanism* is configured. It does **not** prove `KAD_TOKEN` was resolved
  or that initialize succeeded. Always verify with a real tool call (below).

### Direct MCP vs hosted/plugin connector

Codex may also expose a **hosted/plugin** Kad connector (OAuth), often
namespaced like `mcp__codex_apps__kad_dev`. That is a **different** integration.
Use only the direct server named `kad` configured above.

- Do not route setup or verification through the hosted connector.
- An OAuth error such as `UNAUTHORIZED` / `oauth_refresh_token_missing` /
  "Reauthentication required" from the hosted connector is **not** a failure of
  the direct bearer setup — do not open Plugins to "reconnect Kad" for that.
- If tool discovery only offers the hosted connector after you configured
  direct MCP, restart Desktop and confirm `[mcp_servers.kad]` points at this
  host's URL with `bearer_token_env_var = "KAD_TOKEN"`.

## OpenCode — `opencode.json`

Merge into `opencode.json`, then export `KAD_TOKEN` in your shell:

```json
{
  "mcp": {
    "kad": {
      "type": "remote",
      "url": "https://kad.dev/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:KAD_TOKEN}" }
    }
  }
}
// then:  export KAD_TOKEN=<KAD_TOKEN>
```

## Cursor, Windsurf, GitHub Copilot, and all other agents

Add to your agent's MCP config file under `"mcpServers"` (streamable HTTP
transport):

```json
"kad": {
  "url": "https://kad.dev/mcp",
  "headers": { "Authorization": "Bearer <KAD_TOKEN>" }
}
```

## Verify

Call the kad MCP tool `list_projects` on the **direct** MCP server named `kad`
(not a hosted/plugin connector). A successful reply — even an empty list — means
the connection works.

- HTTP 401 → token wrong or missing; ask the user to re-copy it and re-run setup.
- OAuth / "Reauthentication required" / `oauth_refresh_token_missing` → you hit
  a hosted connector, not the direct bearer server; reconfigure and retry.
- For Codex: do not treat `codex mcp list` alone as proof of connectivity.

Once verified, tell the user setup is complete and suggest a first step,
for example: "create a project on kad.dev and deploy this repo".

The agent can: scaffold & push code · create projects · build · read status +
logs · set env vars · promote · clean up.