> ## Documentation Index > Fetch the complete documentation index at: https://docs.fermata.run/llms.txt > Use this file to discover all available pages before exploring further. # What you can ask Claude to do through MCP > Requests you type to Claude Code once Fermata's MCP server is connected, grouped by what you want done, and the MCP tool that each request turns into. You do not call the tools yourself. You ask Claude in plain words, and Claude picks the tool. This page lists the requests that map cleanly onto what the server offers, grouped by what you are trying to get done. The [tool reference](https://docs.fermata.run/reference/mcp-tools.md) has every argument. Claude finds the project from the directory you started it in. Run it inside a repository Fermata already knows and "my pieces" means that project's pieces. Anywhere else, name the project, or ask Claude to register the directory first. ## See what needs you | You type | What happens | | - | - | | "What needs me in Fermata?" | `list_pieces` returns every piece with its phase and the decision waiting on you, and the drafts in your Backlog. | | "Show me the spec for the upload retry piece." | `get_artifact` returns the spec as written, not a summary. Strategy, summary, learnings, and analysis read the same way. | | "Why did the work review fail?" | `get_artifact` with the work review returns the verdict and the agents it failed. | | "What did agent 3 hand off?" | `get_artifact` with `handoff` returns that agent's handoff. | | "Which sessions are waiting on an approval?" | `list_sessions` flags every session sitting on a tool approval. | | "Show me the last 20 messages of that session." | `get_session` with a transcript tail. | `get_piece` is the one Claude reaches for before it acts. It returns the agent graph, the linked sessions, and `legalActions`: exactly what the piece accepts right now. An action outside that list fails and names the ones that would work, so Claude never has to guess. ## Start work | You type | What happens | | - | - | | "Create a piece: add a retry button to failed uploads." | `create_piece` starts the spec interview from your sentence. When the interview asks something, Claude relays the question and sends your answer back with `piece_action` `interviewMessage`. | | "Start SUP-12 on Auto." | `create_draft` with `issue` `SUP-12`, lane `auto`, and `release`: the issue is filed and started in one call. | | "Start these five bugs as Auto pieces: SUP-12, SUP-14, SUP-15, SUP-19, SUP-20." | Five `create_draft` calls, one per key, each released on Auto. | | "File SUP-31 in my Backlog; I'll start it later." | `create_draft` with `issue` and no `release`. The card waits in the Backlog. | | "Here is my spec; it covers SUP-12 and SUP-13. File it." | `create_draft` with your `spec` and `keys`. The tickets are linked, not fetched, and the pull request closes both. | | "Register this repo with Fermata." | `register_project` adds the directory as a project. It must be a git repository with at least one commit. | ### Drafts A draft is a card in the Backlog that waits until you release it. Filing one does not start anything, with one exception: a Loop-lane draft filed while that project's Loop is playing starts at once, because Play is that lane's standing release. | You type | What happens | | - | - | | "Move that draft to the Loop lane." | `update_draft` with `lane`. The title, seed, spec, model, and linked tickets change the same way. | | "Drop the draft about dark mode." | `cancel_draft` deletes it and anything staged with it. | | "Release the three drafts in my Backlog." | `release_draft` on each. A Manual or Loop draft runs its spec step; an Auto draft runs the whole piece up to Review. | Releasing keeps the draft's id, so a piece Claude filed is the same id once it runs. ### From an issue `create_draft` takes `issue`: a Linear key like `SUP-12`, or a GitHub key like `owner/repo#12`. Fermata fetches the issue through the Stream Source linked to the project, files it as a draft whose spec is the issue, and formats it into a full spec when the draft is released. The branch carries the key and the pull request closes the issue, exactly as when you [start from an issue](https://docs.fermata.run/loop/from-an-issue.md) in the app. An issue still blocked by open ones is filed anyway, and the result names the blockers so Claude can tell you. This needs **Loop intake**, another [Edge](https://docs.fermata.run/configuration/edge.md) feature, and a connected Stream Source. Without them the call fails with a sentence saying which is missing. When you wrote the spec yourself, pass the tickets as `keys` instead. Fermata checks every key against the tracker before it files anything, and one key it cannot verify fails the whole call ("Couldn't verify SUP-12: " and the reason). That check exists because a wrong key would put a closing line for an unrelated ticket in your pull request. ## Move a piece along Every step below is one `piece_action` call. Each one is legal only in the phase where the app would offer the same button. | You type | Action | | - | - | | "Approve the spec." | `approveSpec`, on the Manual lane: Fermata writes the strategy next. | | "Approve the spec and run it on Auto." | `approveSpec` with lane `auto`: the rest runs unattended. | | "Write the strategy again." | `generateStrategy`. | | "Approve the strategy." | `approveStrategy`: Fermata splits the work into agents. | | "Split it into agents again." | `decompose`. | | "Start the agents." | `startExecution`. | | "Pause the run." | `pauseAgents`: no new agents start, and running ones finish their turn. | | "Resume it." | `resumeAgents`. | | "Stop the agents on upload-retry." | `stopAgents`. Always asks you on your Mac first. | | "Recover the failed agents." | `retryFailedAgents` recovers every failed agent at once. | | "Move it to review." | `continueToReview`. | | "Approve agent 2." | `approveTask`. | | "Run a code review." | `runCodeReview`, while the **Code review** Edge feature is on. Claude reads the findings later with `get_artifact`. | ### Change the lane "Put upload-retry on the Loop lane" is `setLane`. It is legal from the Spec step through planning, before agents run, and not while an interview turn or a plan build is in progress. Moving to Loop hands the piece to the Loop, which runs it while the project's Loop is playing. See [lanes](https://docs.fermata.run/control/lanes.md). `approveSpec` takes only Manual and Auto, and refuses Loop. To put a piece on the Loop lane, use `setLane`. ### Ask for changes "Request changes on upload-retry: disable the retry button while offline" is `requestChanges` with your text. It starts a feedback session in the piece's worktree, for the whole piece. It is legal at Review and on a completed piece whose branch still exists. ### Send failed work back When the work review fails, "send the failed agents back, and tell them to keep the old API" is two steps. `sendBackToAgents` sends the agents the review named back, each with the review's findings and your guidance (up to 2,000 characters) in its brief. The piece lands paused, so Claude calls `resumeAgents` next. To send only some of them back, name them; Claude reads the list from the work review first. ### Steer a failed agent When an agent fails during the run and you know the fix, Claude can tell it rather than retry it blind. Each agent in `get_piece` says which of these apply right now, and why not when one doesn't. * "Retry agent 3, and tell it `files` is a comma-separated string" is `retryFailedAgents` with that agent and your guidance (up to 2,000 characters). An agent whose session can be steered gets the note as its continue message; one that starts fresh gets it in its brief. * "Agent 3's brief is wrong, it should read the config from `.env`" is `editTaskBrief`, while the run is paused or stopped. Nothing starts until Claude calls `retryFailedAgents`, which starts the agent fresh on the new brief. The agent's card shows the brief changed over MCP. * "Tell agent 3 to use the existing helper" is `messageTask`, while the agent's session is idle or failed. It is the same as typing into the session in Fermata: a failed agent runs again with the turn. * "Answer agent 3's question: use Postgres" is `answerTaskQuestion`. Tool approvals and plan approvals stay yours, and are refused. Messages and answers from Claude show in the transcript and the activity as sent over MCP. With **Ask before runs and pull requests** on, each of these waits for a card first. When the review failed only one agent's work, "resume agent 7 and tell it to commit" is `resumeTask`. It sends that agent's own session the review's findings and your guidance, and leaves every other agent and the run as they are. If the old session can't be resumed, a fresh one starts with the agent's brief and the findings, and Fermata tells you so. Once the agent commits, the work review runs again. Only one resume runs on a piece at a time. With **Ask before runs and pull requests** on, it waits for a card first. ## Finish | You type | What happens | | - | - | | "Open the pull request." | `createPR`. Without a title or body, Fermata writes both from the diff. Legal at Review, when the agents have finished, and on a completed piece that has no pull request yet. | | "Open it as a draft PR." | `createPR` with `isDraft`. | | "Open a PR for every finished piece." | Claude calls `list_pieces`, keeps the completed pieces with no pull request, and calls `createPR` on each. One failure leaves that piece as it was and does not stop the others. | | "Mark it done." | `markDone` removes the worktree and completes the piece. Always asks you on your Mac first. | | "Confirm it's done." | `confirmDone` acknowledges a completed piece. | | "Archive the finished pieces." | `archive` on each. Nothing is deleted; `unarchive` brings one back. | Merging is not on the list. Fermata opens the pull request and stops there; you merge. ## Work on it yourself "Open the upload-retry piece here, I want to fix something by hand" is `open_piece_workspace`. Fermata gets the piece's worktree ready, recreating it from the branch if it was removed, and returns the path, the branch, the spec, and the strategy. It does not move your session: Claude asks you before it changes directory. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.