# MCP feature reference

A complete list of what the PM on Rails MCP can do, grouped by what you are trying to accomplish. You do not normally need to memorize the English tool names — ask Claude Web / Claude Code / Codex in plain language and the agent picks the operations it needs.

![PM on Rails MCP feature reference. Available operations in a list. Before: you returned to the UI to create things. After: you can read, create and change from the conversation.](https://pmonrails.com/docs-img/mcp-tools.png)

This page is a reference closer to API documentation. If you would rather start from when to use which tool and worked examples, see [Claude Web, Claude Code, and MCP integration](https://pmonrails.com/en/docs/mcp.md).

## Behavior shared by everything

- **Permissions** — calls run within the workspace and scopes tied to the PAT. Data in another workspace is not readable.
- **Projects** — most operations either take a target project or require you to select the connected project first.
- **Writes** — creation, updates, deletion, and status changes go through PM on Rails' business rules. They change the same data the screens do.
- **History** — task statuses, comments, decisions, document approvals, upstream changes, and anything else you may need to trace later are kept as history or relationships.
- **Bulk processing** — when you combine several operations, there is an operation that rolls everything back if one fails partway.

## Connection and projects

| What you can do | Main tools |
| --- | --- |
| List the projects you can work with | `list_projects` |
| Choose the project to work on | `connect_project` |
| Switch the display language | `update_language` |
| Get a rough overview of a project | `get_project_overview` |
| Check the autonomy policy of the connected tools | `get_tool_autonomy` |
| Check requirements for ambiguity | `list_demands` / `list_stories` / `list_scenarios` / `list_questionnaire_questions` / `list_feedback` |

## Requirement cards

| What you can do | Main tools |
| --- | --- |
| List requirement cards | `list_demands` |
| Read a requirement card in detail | `get_demand` |
| Create a requirement card | `create_demand` |
| Update the title, body, MoSCoW, score, rationale, and so on | `update_demand` |
| Archive / restore a requirement card | `archive_demand` / `restore_demand` |
| Permanently delete a requirement card | `delete_demand` |
| Find similar requirement cards | `search_similar_demands` |
| Read the whole spec context around a requirement card | `get_demand_context` |

## Requirements and constraints

| What you can do | Main tools |
| --- | --- |
| List requirements | `list_requirements` |
| Read a requirement in detail | `get_requirement` |
| Create a requirement | `create_requirement` |
| Update a requirement's content or relationships | `update_requirement` |
| Archive / restore a requirement | `archive_requirement` / `restore_requirement` |
| Permanently delete a requirement | `delete_requirement` |
| Find similar requirements | `search_similar_requirements` |

## Stories

| What you can do | Main tools |
| --- | --- |
| List user stories | `list_stories` |
| Create a user story | `create_story` |
| Update the overview, actor, value, status, and so on | `update_story` |
| Link / unlink a story and a requirement card | `link_story_demand` / `unlink_story_demand` |
| Link / unlink a story and a requirement | `link_story_requirement` / `unlink_story_requirement` |
| Write a story out to a GitHub issue / sync it | `sync_story_to_github` |
| Archive / restore a story | `archive_story` / `restore_story` |
| Permanently delete a story | `delete_story` |
| Find similar stories | `search_similar_stories` |

## Acceptance scenarios

| What you can do | Main tools |
| --- | --- |
| List scenarios | `list_scenarios` |
| Read a scenario | `read_scenario` |
| Create a Given / When / Then scenario | `create_scenario` |
| Update the scenario text, type, preconditions, and so on | `update_scenario` |
| Change a scenario's status | `update_scenario_status` |
| Replace a scenario with a new version | `supersede_scenario` |
| Archive / restore a scenario | `archive_scenario` / `restore_scenario` |
| Permanently delete a scenario | `delete_scenario` |
| Find similar scenarios | `search_similar_scenarios` |

`create_scenario` creates the SDLCScenario, the scenario KanbanTask, and the place to record scenario tests all at once. The generated scenario task is the anchor for implementation, pull requests, and TestResults; it does not hold the Gherkin or scenario_type. Record the result row after the test with `create_test_result(task_id=<scenario task id>, status=...)`.

## Tasks and the development flow

| What you can do | Main tools |
| --- | --- |
| List tasks | `list_tasks` |
| Find similar tasks | `search_similar_tasks` |
| Read a task in detail | `get_task` |
| Create a task | `create_task` |
| Update a task's title, description, estimate, assignee, and so on | `update_task` |
| Start a task | `start_task` |
| Move a task to in progress, in review, done, and so on | `update_task_status` / `complete_task` |
| Assign a task to yourself | `assign_task_to_me` |
| Link / unlink a task and a story | `link_task_story` / `unlink_task_story` |
| Permanently delete a task | `delete_task` |
| Search pull requests in the connected repository | `search_github_pull_requests` |
| Link a pull request to a task | `link_pr` |
| Find and recover tasks left behind by a missing link | `reconcile_task_prs` |
| Mark a task spec that changed after its pull request as reviewed | `confirm_task_spec_change` |
| Suggest an effort estimate | `suggest_estimate` |

`create_task` / `update_task` are the tools for filing, editing content, and recording the current state. When you move into implementation, finish the creation and updates you need, then call `start_task(task_id)`. Passing `kanban_status='doing'` to create or update does not stamp started_at and does not evaluate the Definition of Ready gate for starting work. The dedicated start entry is `start_task`. That call makes the caller the assignee if nobody owns the task, stamps started_at if the task has not been started, evaluates the Definition of Ready, and drops the task into the active sprint when it has no sprint yet and exactly one active sprint exists. If there is no active sprint, confirm the start date, end date, and cadence, create it with `create_cycle`, then call `start_task` again. To take over someone else's in-progress task, use `assign_task_to_me` explicitly. started_at is kept as the time of the first start, and tasks whose assignee changed after work began are excluded from the per-person effort correction samples. Use `update_task_status` when you only need to move the status.

## Bugs and defects

| What you can do | Main tools |
| --- | --- |
| Find which scenario a bug breaks | `resolve_bug_destination` |
| File a bug task | `create_bug_task` |
| Record what a bug affects | `update_bug_affects` |
| List the bugs affecting a given scenario or requirement | `list_bugs_affecting` |
| Mark a bug as resolved | `resolve_bug` |
| Promote a bug into a requirement candidate to prevent recurrence | `promote_bug_to_requirement` |

## Roadmap and sprints

| What you can do | Main tools |
| --- | --- |
| List epics | `list_epics` |
| Create an epic | `create_epic` |
| Update an epic's content or status | `update_epic` |
| Link / unlink an epic and a story or standalone task | `link_epic_work_item` / `unlink_epic_work_item` |
| List sprints | `list_cycles` |
| Create a sprint | `create_cycle` |
| Update a sprint's name, dates, scope, and so on | `update_cycle` |
| Change a sprint's status | `update_cycle_status` |
| Adopt the tasks completed inside a sprint | `adopt_completed_tasks` |
| Check sprint progress (completed and remaining counts and estimates, estimate coverage, completed items waiting to be adopted) | `get_cycle_progress` |

## Stakeholders

| What you can do | Main tools |
| --- | --- |
| List stakeholders | `list_stakeholders` |
| Create a stakeholder | `create_stakeholder` |
| Update a stakeholder's details | `update_stakeholder` |

## Open questions and feedback

| What you can do | Main tools |
| --- | --- |
| List open questions | `list_questionnaire_questions` |
| Create a question for a stakeholder | `create_questionnaire_question` |
| Edit an open question's wording, target, or status | `update_questionnaire_question` |
| Record an answer to an open question | `answer_questionnaire_question` |
| Resolve / reopen an open question | `resolve_questionnaire_question` / `reopen_questionnaire_question` |
| Before resolving, check the answer reached every affected spec | `resolve_questionnaire_question` (`dry_run=true`) |
| Share an open question to Slack | `share_questionnaire_question_to_slack` |
| Delete an unnecessary open question | `delete_questionnaire_question` |
| Draft a proposal that reflects an answer into requirements and stories | `create_question_reflection_proposal` |
| See the friction, requests, and hints of defects that came out of real usage | `list_feedback` |
| Create feedback | `create_feedback` |
| Draft a proposal that reflects feedback into requirements and stories | `create_feedback_reflection_proposal` |
| Ask for further clarification | `request_clarification` |

## Comments and work notes

| What you can do | Main tools |
| --- | --- |
| Add a comment | `add_comment` |
| List comments | `list_comments` |
| Update a comment's body or status | `update_comment` |
| Resolve / reopen a comment | `resolve_comment` / `reopen_comment` |
| Link a comment to a requirement, story, task, and so on | `link_comment_to_sdlc_node` |
| Leave an approach you tried and abandoned as a work note | `record_failed_approach` |

## Decisions and ADRs

| What you can do | Main tools |
| --- | --- |
| Record a decision to adopt / reject / defer a requirement | `create_decision` |
| List requirement decisions | `list_decisions` |
| Create an ADR | `create_architecture_decision` |
| Update an ADR | `update_architecture_decision` |
| Supersede an ADR with a newer decision | `supersede_architecture_decision` |
| Assign an ADR to a project | `assign_architecture_decision_project` |
| List ADRs | `list_architecture_decisions` |
| Delete an ADR | `delete_architecture_decision` |
| Find similar decisions | `search_similar_decisions` |

## Documents and knowledge

| What you can do | Main tools |
| --- | --- |
| List folders | `list_folders` |
| Create a folder | `create_folder` |
| List documents | `list_documents` |
| Read a document | `get_document` |
| Create a document | `create_document` |
| List / create design doc folders | `list_design_folders` / `create_design_folder` |
| List / create design docs | `list_design_documents` / `create_design_document` |
| Update a document's body | `update_document_body` |
| Delete a document | `delete_document` |
| Generate a document draft with AI | `generate_document_draft` |
| Request a document review | `request_document_review` |
| Approve / send back a document | `approve_document` / `reject_document` |
| List a document's versions | `list_document_versions` |
| List a document's approval events | `list_document_approval_events` |
| Read a specific document version | `get_document_version` |
| Revert to an earlier document version | `revert_document_version` |

## Test results

| What you can do | Main tools |
| --- | --- |
| List test results | `list_test_results` |
| Record a test result | `create_test_result` |
| Link a test result to a task | `link_test_result_to_task` |
| Check whether scenario verification is newer than the current spec | `get_scenario_verification_freshness` |
| Check the completion evidence for a scenario before a pull request | `check_pr_quality_gate` |
| Surface test results that are not linked to anything | `audit_unlinked_test_results` |

### Keep a screenshot with a test run

Upload a local image or video with `upload_attachment(project_id, file_path)`. `file_path` must be accessible from the host running the pm-on-rails CLI MCP proxy. Relative paths resolve against the proxy working directory. The proxy reads the file there, so the attachment never costs agent tokens (inlining Base64 costs about 190k tokens for a 200KB screenshot). Put the returned `attachment_id` in `evidence[].attachment_id` when calling `create_test_result` to retain it as screenshot or video evidence. Use `/api/attachments/{id}` when you need to display it in the UI or scenario description. The server cannot open a path on the CLI MCP proxy host, so a client that does not go through the CLI MCP proxy gets `attachment.file_path_not_resolved` for `file_path`; pass `content_base64` in that case only.

## Change tracking and applying diffs

| What you can do | Main tools |
| --- | --- |
| List upstream changes | `list_upstream_changes` |
| Mark upstream changes as reviewed | `acknowledge_upstream_changes` |
| List proposed downstream updates | `list_cascade_proposals` |
| List applied, reflected, and other proposal history | `list_cascade_proposal_history` |
| Dry-run or reconcile the proposal inbox against the current specification | `reconcile_project_cascade_proposals` |
| Apply a proposed update | `apply_cascade_proposal` |
| Apply proposed updates in bulk | `apply_cascade_proposals` |
| Accept / reject a proposed update | `decide_cascade_proposal` |

## Exploration, quality checks, and analysis

| What you can do | Main tools |
| --- | --- |
| Trace the rationale from requirement to requirement detail, story, scenario, and task | `get_traceability` |
| Check where rationale or downstream items are missing | `check_traceability_completeness` |
| Check project statistics | `get_project_stats` |
| Get the weekly PM review (a summary of overdue, nearly due, stalled, unassigned, WIP imbalance, waiting on stakeholders, and missing traceability) | `generate_weekly_pm_review` |
| Analyze rework trends | `analyze_rework` |
| List the event history | `list_events` |

## Bulk operations

| What you can do | Main tools |
| --- | --- |
| Run several creations, updates, and links together | `execute_operations` |

Bulk operations exist so that a failure partway does not leave half-finished changes behind. Use them when you hand off things like filing a large number of tasks, linking items after generating stories, or adding several comments.

## Operations that need care

- **Deletions** — permanent deletion also loses the history, so archiving is usually preferable.
- **Version replacement** — superseding a scenario or an ADR keeps the old version and moves to a new one. It is not a plain overwrite.
- **GitHub sync** — GitHub is the outbound integration for the MCP development flow. Manage day to day over MCP and use this when you need to connect to issues and pull requests.

<!-- pm-on-rails:mcp-tools-auto -->
## Registered MCP tools (auto-synced)

Tools registered in the backend with `name="..."` are listed here on every build / test run. See the tables above for what each is for.

- `add_comment`
- `apply_cascade_proposals`
- `approve_document`
- `archive_demand`
- `assign_project_member`
- `assign_task_to_me`
- `check_pr_quality_gate`
- `complete_task`
- `confirm_task_spec_change`
- `create_actor`
- `create_architecture_decision`
- `create_bug_task`
- `create_change_request`
- `create_cycle`
- `create_decision`
- `create_demand`
- `create_design_document`
- `create_design_folder`
- `create_epic`
- `create_requirement`
- `create_scenario`
- `create_story`
- `create_task`
- `delete_questionnaire_question`
- `execute_operations`
- `generate_weekly_pm_review`
- `get_change_request`
- `get_cycle_progress`
- `get_demand`
- `get_demand_context`
- `get_embedding_coverage`
- `get_figma_design_context`
- `get_mcp_usage_guide`
- `get_project_overview`
- `get_project_stats`
- `get_story`
- `get_task`
- `get_traceability`
- `link_epic_work_item`
- `link_pr`
- `link_story_demand`
- `list_actors`
- `list_architecture_decisions`
- `list_bugs_affecting`
- `list_cascade_proposal_history`
- `list_change_requests`
- `list_comments`
- `list_cycles`
- `list_decisions`
- `list_demands`
- `list_design_documents`
- `list_design_folders`
- `list_documents`
- `list_feedback`
- `list_project_members`
- `list_requirements`
- `list_stories`
- `list_tasks`
- `list_workspace_members`
- `promote_bug_to_requirement`
- `read_scenario`
- `reconcile_project_cascade_proposals`
- `reconcile_task_prs`
- `remove_project_member`
- `reopen_comment`
- `reopen_questionnaire_question`
- `request_document_review`
- `resolve_bug`
- `resolve_bug_destination`
- `resolve_comment`
- `resolve_questionnaire_question`
- `revert_document_version`
- `search_github_pull_requests`
- `search_similar_decisions`
- `search_similar_demands`
- `search_similar_requirements`
- `search_similar_tasks`
- `share_questionnaire_question_to_slack`
- `start_task`
- `suggest_estimate`
- `supersede_architecture_decision`
- `supersede_scenario`
- `sync_story_to_github`
- `unlink_epic_work_item`
- `unlink_story_demand`
- `update_architecture_decision`
- `update_bug_affects`
- `update_comment`
- `update_cycle`
- `update_demand`
- `update_epic`
- `update_language`
- `update_questionnaire_question`
- `update_requirement`
- `update_scenario`
- `update_scenario_status`
- `update_story`
- `update_task`
- `update_task_status`
- `upload_attachment`

---

https://pmonrails.com/en/docs/mcp-reference