# MCP tools

> The tools your coding agent uses to pick up tasks, report progress and track the goal.

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

---

# MCP tools

These are the tools your agent sees after you [connect your coding tool](/guides/features/mcp-client-setup). The repo's `AGENTS.md` tells the agent to use them in this order.

## The routine

1. **Start a session:** `list_goals` (what "shipped" means and the next milestone), then `start_build_session`. It picks the next ready task, moves its card to **In Progress**, and returns the build packet: acceptance criteria, files to touch, branch name and checks.
2. **While working:** after each commit, `record_build_progress` with a one-line summary.
3. **Before committing:** `validate_code_diff` checks the change against the accepted PRD and decisions.
4. **Task done:** `submit_build_evidence` (checks run, commit) and `complete_task`. The card moves to **Done**. Then `start_build_session` again.
5. **Milestone done:** `complete_milestone`. **Deployed:** `record_deployment`, so the goal counts it.
6. **Stuck:** `report_blocker` posts the question to Discord and your project page. Press **Answer** in Discord (or answer on the page); the agent receives it with its next Builderthread call, so you don't need to be at the computer it runs on. When it needs keys, `request_env_values` tells you which file and how to get each one: add them, then press **I've added them** in Discord.

## All tools

| Tool | Scope | What it does |
| --- | --- | --- |
| `list_projects` | `projects:read` | Lists the project this connection can use. |
| `get_agent_context` | `prd:read`, `build:read` | Accepted PRD, decisions and open tasks. |
| `get_next_actions` | `build:read` | Ready tasks in order, with what blocks the others. |
| `start_build_session` | `build:read`, `progress:write` | Starts or resumes the next task and returns its build packet. |
| `get_build_packet` | `build:read` | The packet for a specific task. |
| `record_build_progress` | `progress:write` | Records progress on the current task. |
| `submit_build_evidence` | `progress:write` | Attaches checks, test output or a commit to the task. |
| `complete_task` | `tasks:complete` | Finishes the task and moves it to Done once a pushed commit is attached, the task's acceptance tests are written and CI is green on that commit. |
| `list_goals` | `projects:read` | Goals, what counts as shipped, and milestone status. |
| `complete_milestone` | `tasks:complete` | Marks a goal milestone done with evidence. |
| `report_blocker` | `progress:write` | Asks the user for something the agent cannot do itself. |
| `request_env_values` | `progress:write` | Asks you to put keys the agent cannot get itself into a local env file. You get what each is for and how to get it in Builderthread and Discord, and type the values into the file yourself. |
| `pause_task` | `progress:write` | Puts a task back as not done while it waits on your answer, so the agent moves on. It comes back when you answer. |
| `get_user_answers` | `projects:read` | Reads the user's answers to its questions. Answers also arrive appended to the agent's next call. |
| `record_deployment` | `progress:write` | Records a working deployment (URL and commit). Never secrets. |
| `validate_code_diff` | `prd:read`, `build:read` | Reviews a diff against the PRD and decisions before commit. |
| `propose_prd_change` | `changes:propose` | Proposes a product change for you to approve. |
| `record_decision` | `changes:propose` | Records a lasting technical decision. |

The connection's scopes are `projects:read`, `prd:read`, `research:read`, `build:read`, `skills:read`, `changes:propose`, `progress:write` and `tasks:complete`.

## Plan limits

- Reading works for anyone on an active plan with MCP agent connections (Builder, Pro, and Studio).
- Starting tasks, recording progress, and calling `complete_task` or `complete_milestone` require Builder or above.
- Every paid plan includes all build packets for your project with no monthly cap.

When a call is not part of the plan, the agent gets a clear "ask the user to upgrade" message and keeps coding locally.