# Connect your coding tool

> Connect Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI, Kiro or OpenCode so the agent can pick up tasks and report progress.

- Source: https://builderthread.dev/guides/features/mcp-client-setup
- Format: Raw Markdown
- Platform: Builderthread (https://builderthread.dev)
- AI Reading Mode: Optimized for agents (Claude Code, Cursor, Codex, Windsurf)

---

# Connect your coding tool

Your repo already contains the Builderthread MCP configuration for your project. MCP is how your coding agent reads tasks, gets build packets and moves cards on the board. You only approve a browser sign-in once.

You need a plan that includes a coding-agent connection (Builder and above).

## Easiest: paste the start prompt

Open your project, go to the **Build** tab and copy the **Start building** prompt into your coding tool. It clones the repo, connects MCP and starts the first task. The steps below are what the agent does, if you want to do it yourself.

### Claude Code

1. Clone the repo and open a terminal in it, then run `claude`.
2. Claude Code finds `.mcp.json` and asks whether to use the `builderthread` server. Approve it.
3. Type `/mcp`, select `builderthread` and choose **Authenticate**. Your browser opens; sign in to Builderthread and approve the project.

Without the repo, you can add it by hand: `claude mcp add --transport http builderthread <your project MCP URL>`.

### Cursor

1. Open the cloned repo in Cursor. It reads `.cursor/mcp.json`.
2. Open **Settings → MCP**. Next to `builderthread`, select **Login** (or **Connect**) and approve the project in the browser.
3. The tools appear in Agent mode.

### Codex

1. Open the cloned repo with Codex and trust the project when asked. Codex reads `.codex/config.toml` for trusted projects.
2. Run `codex mcp login builderthread` and approve the project in the browser.

### Windsurf

Windsurf keeps MCP servers in its own settings rather than in the repo.

1. Open **Windsurf Settings → MCP servers → View raw config**.
2. Copy the `builderthread` entry from `.builderthread/mcp/windsurf.json` in your repo into that file and save.
3. Refresh the server list and approve the browser sign-in.

### VS Code (GitHub Copilot)

1. Open the cloned repo in VS Code. It reads `.vscode/mcp.json`.
2. Open that file and select **Start** above the `builderthread` server (or use **MCP: List Servers**). Approve the browser sign-in.
3. Use Copilot in Agent mode; it also reads `AGENTS.md`.

### Gemini CLI

1. Run `gemini` in the cloned repo. It reads `.gemini/settings.json` and `GEMINI.md`.
2. Type `/mcp auth builderthread` and approve the project in the browser.

### Kiro

1. Open the cloned repo in Kiro. It reads `.kiro/settings/mcp.json` and the steering file in `.kiro/steering/`.
2. In the MCP servers panel, connect `builderthread` and approve the browser sign-in.

### OpenCode

1. Open the cloned repo. OpenCode reads `opencode.json` and `AGENTS.md`.
2. Run `opencode mcp auth builderthread` and approve the project in the browser.

## Your project's MCP URL

The configs point to a URL like `https://<builderthread-domain>/api/mcp/<project-id>`. It is tied to one project. The repo contains no tokens or passwords: sign-in happens in your browser.

## If something does not work

- **No tools show up:** restart the MCP server in your tool, then sign in again.
- **Asked to sign in again:** your session expired or was revoked. Sign in again from the tool's MCP settings.
- **"This action needs an active plan" (402):** the action is not part of your plan. Upgrade in **Settings → Billing**; your agent can keep coding locally meanwhile.
- **The repo says MCP setup is pending:** the agent works from the PRD and task list in the repo until your workspace has a public address.

Next: [the MCP tools your agent uses](/guides/features/mcp-agent-gateway).