Builderthread guides

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.

On this page

Connect your coding toolEasiest: paste the start promptClaude CodeCursorCodexWindsurfVS Code (GitHub Copilot)Gemini CLIKiroOpenCodeYour project's MCP URLIf something does not work