# Claude Web, Claude Code, and MCP integration

PM on Rails supports **MCP (Model Context Protocol)**. External AI tools such as Claude Web, Claude Code, and Codex can read and write your project graph directly. Unlike the in-app AI assistant, **a broad set of both read and write tools is available**, so you can work on requirements, tasks, and scenarios from inside management work and implementation work alike.

## What MCP is

MCP is the common standard for handing an AI tool a set of "PM on Rails instruments". Rather than reasoning from the conversation alone, Claude Web and Claude Code call the tools PM on Rails exposes, read the real data, and save the changes that are needed.

- **They work on the same graph** — whether you go through the screens, the AI assistant, Claude Web, Claude Code, or Codex, requirement cards, requirements, stories, scenarios, and tasks are the same data.
- **Natural language becomes tool calls** — a request like "look at the impact of this requirement" or "start this task" is turned into read and update operations on the PM on Rails side.
- **Reads and writes are handled separately** — investigation runs through read tools; creation and updates run through write tools. Writes follow the PAT's permissions and the project's rules.
- **Responses carry what you need next** — starting a task returns the branch name, the identifier line for the pull request body, warnings about upstream changes, and other things you use directly while developing.

## When to use which

| Where you use it | Who it suits | Typical use |
| --- | --- | --- |
| Claude Web | PM / PdM / business | Organizing requirements, checking priorities, creating stories and open questions, updating after meetings, checking impact |
| Claude Code | Engineers | Picking a task, checking background and acceptance criteria, starting work, creating branches, checking the spec mid-implementation, linking pull requests |
| Codex | Engineers / reviewers | Working through tasks while reading existing code, testing, fixing, opening pull requests, comparing spec against implementation |
| The PM on Rails screens | The whole team | Lists, roadmap, board, review, settings, permissions |

A PM connects Claude Web to MCP and drives management work through conversation: "pull the unorganized requirements out of yesterday's meeting notes", "show me only the Must stories", "tell me which tasks this change affects". Engineers connect Claude Code / Codex to the same MCP and move into development work: "pick a task I can start next", "read the acceptance scenarios before implementing", "give me the identifier line for the pull request body".

## Setup

![PM on Rails token management. Issue a PAT for the MCP connection. Before: agent credentials lived in a personal note. After: the connection stays inside the project's permissions.](https://pmonrails.com/docs-img/mcp-tokens.png)

1. For Claude Code, run `npm install -g pm-on-rails` → `pm-on-rails login` → `pm-on-rails mcp install` in a terminal, in that order. `login` opens an approval screen in the browser and stores the token in your OS keychain, so you do not handle the token by hand.
2. For other tools, issue a **personal access token (PAT)** in Token management under "Personal settings → Integrations" (shown in plain text only at issue time; you can pick scopes and an expiry). Configure the MCP server endpoint and the PAT in the external tool.
3. A PAT is fixed to **one workspace**. To work with other workspaces, issue one token per workspace.

> A PAT is a secret. If you lose it, revoke it and issue a new one (the plain text cannot be retrieved again).

## How it works

1. **The external AI tool connects to the MCP server** — the PAT establishes the workspace and permissions.
2. **The AI reads the list of available tools** — it only sees the operations PM on Rails allows, such as creating requirements, searching traceability, and updating tasks.
3. **It interprets your request** — a request like "check what we are missing around login" is broken down into the read and update tools it needs.
4. **PM on Rails executes against real data** — not the AI's guesses, but the project graph in Neo4j, permissions, state transition rules, and GitHub integration status.
5. **It returns results and next actions** — the change, the evidence, related nodes, the branch name, the identifier line for the pull request body, and any caveats go back to the external AI tool.

| Category | Main tools | What it does |
| --- | --- | --- |
| Requirement cards | `create_demand` / `update_demand` / `list_demands` / `get_demand` / `archive_demand` | Create and update requirement cards (MoSCoW / scoring), list them, archive them |
| Requirements | `create_requirement` / `update_requirement` / `list_requirements` | Create, update, and list non-functional requirements and constraints (functional specs live in the story overview) |
| Decisions and ADRs | `create_decision` / `list_decisions` / `create_architecture_decision` / `update_architecture_decision` / `supersede_architecture_decision` / `list_architecture_decisions` | Record adoption decisions and architecture decisions (ADRs), change their status, supersede them, list them |
| Stories | `create_story` / `update_story` / `list_stories` / `get_story` / `link_story_demand` / `unlink_story_demand` / `sync_story_to_github` | Create, update, list, and read stories, re-parent them to another requirement card, sync them to GitHub |
| Scenarios | `create_scenario` / `update_scenario` / `update_scenario_status` / `supersede_scenario` / `read_scenario` | Create, update, transition, and supersede Gherkin scenarios |
| Tasks | `create_task` / `update_task` / `start_task` / `update_task_status` / `assign_task_to_me` / `complete_task` / `list_tasks` / `get_task` | Create, update, start, transition, self-assign, and complete tasks |
| Display language | `update_language` | Switch the same User.language the console uses to ja or en |
| Bugs | `resolve_bug_destination` / `create_bug_task` / `resolve_bug` / `update_bug_affects` / `promote_bug_to_requirement` / `list_bugs_affecting` | Find which scenario a bug breaks, file bugs, resolve them, record what they affect, promote them into requirements |
| Planning | `create_epic` / `update_epic` / `create_cycle` / `update_cycle` / `list_cycles` | Create and update epics and sprints (`cycle` is the internal name for a sprint) |
| Integrations | `link_pr` / `search_github_pull_requests` / `sync_story_to_github` | Search and link pull requests, sync issues |
| Exploration | `get_traceability` / `search_similar_demands` / `search_similar_requirements` / `search_similar_decisions` / `get_project_stats` / `get_embedding_coverage` | Follow traceability, search for similar items, statistics, and coverage of the similar-search data |
| Estimation | `suggest_estimate` | Estimate suggestions from an LLM plus a personal correction |
| Documents and design documents | `list_folders` / `create_document` / `get_document` / `update_document_body` / `generate_document_draft` / `list_documents` / `request_document_review` / `approve_document` / `revert_document_version` / `delete_document` / `list_design_folders` / `create_design_folder` / `list_design_documents` / `create_design_document` | Generate, save, update, review, approve, restore versions of, and delete Markdown documents; list and create design doc folders and documents |
| Archive and delete | `archive_*` / `restore_*` / `delete_*` | Archive / restore / delete requirement cards, requirements, stories, and scenarios (children follow) |
| Comments | `add_comment` / `update_comment` / `list_comments` | Add, update, and list comments |
| Bulk | `execute_operations` | Run several operations atomically in a single transaction |
| Usage | `get_mcp_usage_guide` | Return one usage-guide topic (session start, starting work, completion, traceability, and so on) |

> MCP is "the API behind the chat". The conversation is natural language, but the actual reads and writes are recorded as PM on Rails tool calls.

## How scenarios, tasks, and tests relate

`create_scenario` does more than create the `SDLCScenario` that is the source of truth for the acceptance spec. In the same call it also prepares the scenario `KanbanTask` that appears on the board and the link used to record scenario test results.

- **Source of truth for the acceptance spec** — Given / When / Then and the Gherkin are stored in `SDLCScenario`.
- **Implementation anchor** — the scenario `KanbanTask` on the board is the work card that ties implementation, pull requests, bugs, and test results together. It does not copy the Gherkin or scenario_type.
- **Test results** — no `TestResult` row is created at `create_scenario` time. After the run, record pass or fail against the generated scenario task's `task_id` with `create_test_result`.

Filing the same behavior again with `create_task` after `create_scenario` means managing it twice. To fix the scenario text, use the task's `scenario_id` to call `read_scenario` / `update_scenario` / `supersede_scenario`. One-off internal work, investigations, and migrations stay as `create_task(task_type='task')`.

## Reviewing proposed updates on screen (MCP Apps)

`list_cascade_proposals` (the list of updates the AI has drafted for requirements, stories and scenarios) is **shown as a screen in hosts that support MCP Apps, such as Claude Web**. You can read the diff before choosing apply, defer or dismiss, and each of those asks for confirmation first. Hosts without MCP Apps receive the same content as text, so reading it through the conversation works as before. Applying runs through the existing tools with the same permissions and project boundaries.

## What a PM can do in Claude Web

- **Tidy up after a meeting** — from the meeting notes you ingested, surface unorganized requirements, open questions, and priority candidates.
- **Take stock of requirements** — look at only the Must / Should requirements, or hunt for weakly justified and likely duplicate ones.
- **Draft stories** — turn a requirement into a first cut of a user story and its acceptance scenarios.
- **Build an agenda of open items** — gather unanswered and under-discussion questions into a Markdown meeting agenda and save it to the knowledge base.
- **Check the impact of a change** — see which stories and tasks are affected if you change a given requirement.
- **Manage open questions** — keep the stakeholder questions raised by AI review as open items, and reflect the answers into requirements and stories when they arrive.

Example:

```text
Look at the Must requirements around inventory alerts and tell me which ones have no user story yet.
If anything is still unclear, draft it as a question I can send to the stakeholder.
```

## What developers can do in Claude Code / Codex

- **Pick the next task** — find a task you can start from the sprint, the assignee, the dependencies, and the status.
- **Read the background** — walk from the task to the scenario, the story, the requirement, and the original remark to confirm the definition of done.
- **Record that you started** — move the task to in progress with `start_task(task_id)`, recording the assignee, the sprint, and the start point for actual time.
- **Link the branch and the pull request** — use the branch name and the identifier line for the pull request body from the response to link the pull request to the task automatically.
- **Detect spec changes** — if an upstream requirement or scenario changed while you were implementing, you know a re-check is needed before or after the merge.
- **Update after implementing** — complete the task, file bugs, update scenarios, and add open questions right from the flow of your code work.

Example:

```text
Pick one task from the current sprint that I can start.
Read the related story, acceptance scenarios and upstream requirement, and give me the branch name and the identifier line for the pull request body.
```

## Examples

### 1. A PM organizes requirements after a meeting

```text
From the meeting notes I imported today, list the requirement candidates that are not organised yet.
Separate the ones that look like duplicates of existing requirements, the ones I need to confirm with the stakeholder, and the Must candidates.
```

MCP reads documents, requirements, and past decisions, and where it makes sense leaves draft requirement cards and comments. Questions for the stakeholder can stay as open items, so the meeting notes connect all the way to the next action.

### 2. A PM checks the impact of a scope change

```text
I want to change "send inventory alerts to Slack as well as email".
List the stories, scenarios, unfinished tasks and specs I need to check.
```

It follows the chain downstream from the requirement and checks for in-flight tasks and acceptance scenarios that have not been updated. If needed, it can also draft story updates and questions for the stakeholder.

### 3. An engineer starts implementing

```text
Pick a task I can start from the current sprint, assign it to me and move it to in progress.
Give me the background, the acceptance scenarios, any upstream changes to watch out for, the branch name and the identifier line for the pull request body.
```

Task lists, task details, background traceability, assignee changes, and status changes combine to take you from picking a task to recording that you started it. Do any task creation or content updates first with `create_task` / `update_task`, and call `start_task(task_id)` only when you actually start. 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 keeps the time of the first start. Tasks whose assignee changed after work began are excluded from the per-person effort correction samples. If you use the branch name and the identifier line for the pull request body that come back, merging the pull request updates the task and its parent story automatically.

### 4. Checking the spec diff while implementing

```text
Check whether the upstream requirement or scenarios changed after I started this task.
If they did, tell me only the diffs that affect the implementation.
```

It compares the time you started with the update times of upstream nodes to confirm you are not implementing against a stale spec. If there is a diff, the task can be treated as one that needs a re-check before the pull request is merged.

### 5. A reviewer compares a pull request against the spec

```text
Read the acceptance scenarios of the task linked to this pull request and check whether the diff satisfies them.
Point out any missing tests or anything that differs from the spec.
```

Codex and Claude Code can read the code diff while pulling the task, story, and acceptance scenarios over MCP. Review is no longer "just the code" — it can follow the trail all the way to why the spec looks the way it does.

### 6. Taking things outside PM on Rails

```text
Export the stories in this sprint as Markdown.
Create issues for the ones not yet linked to GitHub, and push the latest content for the ones that are.
```

Markdown export and GitHub issue sync are both available, so you are never locked into PM on Rails. Manage and develop comfortably over MCP day to day, and take things out to Markdown or GitHub whenever you need to.

## The big picture of what you can do

MCP covers a wider range of operations than the AI assistant. You do not need to memorize the English tool names. Ask Claude Web / Claude Code / Codex in plain language and the agent picks the operations it needs.

| What you want to do | What is possible |
| --- | --- |
| Organize requirements | Create and update requirement cards, adjust MoSCoW and scores, review lists, archive |
| Record requirements and constraints | Create and update non-functional requirements, constraints, and assumptions, and link them to related requirement cards |
| Record decisions | Adopt / reject / defer decisions, ADRs, superseding old decisions, reviewing the reasoning |
| Create stories | Create and update user stories, re-parent them, add acceptance scenarios |
| Shape scenarios | Create and update Given / When / Then, change status, replace with a new version |
| Move tasks forward | Create and update tasks, change assignee, start, complete, check the board status |
| Handle bugs | File bugs, record resolutions, organize what they affect, promote them into requirements |
| Plan | Epics, sprints, sprint scope, progress |
| Connect to GitHub | Turn stories into issues, push updates to issues, link pull requests to tasks |
| Search and trace | Confirm the rationale from requirement down to task, check impact, search similar requirements and past decisions |
| Estimate | Estimate task effort, corrected by personal history |
| Manage documents | List documents, request review, approve, restore versions, delete |
| Process in bulk | Run many creations and updates at once. If one fails partway, all of them are rolled back |

> To review every MCP operation in plain language, see the [MCP feature reference](https://pmonrails.com/en/docs/mcp-reference.md). It lists the internal tool names too, for developers.

## Type this, get that

Once you have the graph structure in mind (requirement → requirement detail → story → scenario → task), you can hand off whole sequences of operations in natural language.

| What you ask Claude Web / Claude Code | What happens in PM on Rails |
| --- | --- |
| "From the inventory management requirement, build out the story and acceptance scenarios" | Creates the requirement card, the story, and the acceptance scenarios in order |
| "Break down and file the tasks needed to implement this requirement" | Checks the related requirements, stories, and scenarios, then creates several tasks |
| "Tell me the branch for the task I'm working on" | Moves the task to in progress and returns the branch name and the identifier line for the pull request body |
| "List the scenarios this bug affects and turn it into a requirement so it doesn't recur" | Records the affected scenarios and drafts a requirement to prevent recurrence |
| "Check whether we've had similar requirements or decisions around login before" | Searches for similar requirement cards, requirements, and past decisions |
| "Show me what breaks if I change this requirement" | Follows the chain upstream and downstream and lists the affected stories, scenarios, and tasks |
| "Export this story as Markdown" | Takes it out through Markdown export |
| "Turn this story into a GitHub issue" | Creates a GitHub issue and records it as the sync target from then on |
| "Move this story under a different requirement card" | Re-parents the requirement card while keeping the scenarios and requirement links underneath |
| "Build tomorrow's meeting agenda in Markdown from the unanswered open questions and save it to the knowledge base" | Reads the open questions, related stories, and existing documents, drafts Markdown, and saves it as a document |
| "Create these tasks all at once (and roll everything back if one fails)" | Runs the operations in bulk and rolls them all back if one fails partway |

## Automatic pull request ↔ task linking

The intended path is to use the branch name and the identifier line for the pull request body that MCP returns when you start implementing.

- Create your branch with the branch name you got back (for example `feat/9e300a0b-add-login`)
- Put the identifier line you got back (for example `PMR-Task: 9e30...`) on one line of the pull request body

With that, merging the pull request into the default branch moves the task to done automatically and recalculates the parent story (a merge into a feature branch waits until that branch reaches main). GitHub is the outbound integration that supports the MCP development flow. Details in [GitHub integration](https://pmonrails.com/en/docs/github.md).

## How it stays safe

- Every operation stays within the **workspace and project permissions** tied to the token.
- The same business rules and safety checks as the screens (the UI) apply to operations from external tools.
- Output also carries Japanese labels alongside the raw values, which makes it easier for the AI to interpret.

## Next steps

- A lighter version for conversation → [AI assistant](https://pmonrails.com/en/docs/ai-assistant.md)
- Everything you can do → [MCP feature reference](https://pmonrails.com/en/docs/mcp-reference.md)
- How it works → [How the AI works](https://pmonrails.com/en/docs/graphrag.md)

---

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