Claude Code setup

Claude Code can use either server. The hosted server has the full tool set, including the story lifecycle and build runs. The local server runs through the CLI and reads the one project your repository is linked to.

Hosted server

The hosted server steps are on Connect Claude Code to IntentDocs.

A token reads only the workspace it is bound to, for its whole life. See Workspace tokens.

If you ran npx intentdocs setup in the repository, you also have /intent-* slash commands, such as /intent-next to pick up the next story.

Fewer approval prompts

Claude Code asks before every MCP tool call unless the tool is allowed in its settings. npx intentdocs init offers to allow the IntentDocs reads and build-loop tools in the project's .claude/settings.json. It shows the full list and writes nothing unless you answer yes.

It allows these, as mcp__<server>__<tool> rules for each server name it finds in .mcp.json or ~/.claude.json (default intentdocs):

• Reads: list_projects, get_context, get_session_context, list_stories, get_story, get_status, get_build_order, get_vision, get_design, get_run
• Build loop: next_in_run, start_story, report_criteria, save_tests, complete_story, link_pr, add_note

replace_criteria, update_stories, create_stories and cancel_story still ask, because they change the spec or remove work.

Workspace tokens

A token bound to a team workspace reads every open project in that workspace, with your role in it. A token bound to your personal workspace reads your own projects and any project you were invited to.

Some workspaces require an admin to approve new agent tokens. Until one does:

• The token reads your personal workspace and nothing of the team workspace.
• The server's first message says so: "Bound to workspace, awaiting approval — an admin has been asked."
• A call on one of that workspace's projects is refused with the same sentence, not "not found".

A workspace admin's own tokens, and tokens in a workspace that doesn't require approval, are approved when they are created.

A token stops working when you leave the workspace or an admin revokes its access. Every call is then refused with the reason. Connect a new agent from a workspace you belong to.

Your role decides what the agent can do. Reads need any role. Writes need editor or owner. add_note needs comment access. A refused write names the capability it needs.

Local server

The local server runs as a subprocess and talks to Claude Code over stdio. It has 15 tools and six read-only resources. See Tools & resources for the list.

With the CLI

In your repository:

npx intentdocs login
npx intentdocs init
npx intentdocs setup

init links the repository to a project in .intent/config.json. Choose Claude Code when setup asks. It registers the local server in the project's .mcp.json under the name intent, the same entry claude mcp add --scope project intent -- npx intentdocs mcp writes, and keeps any other servers in that file. It also writes the /intent-* slash commands to .claude/commands/. Restart Claude Code and approve the server when it asks. See CLI Reference → Project setup for the rest of what setup does.

Older versions of setup wrote the server to ~/.claude/settings.json, where Claude Code doesn't look. Running setup again removes that entry.

By hand

In the repository, run:

claude mcp add --scope project intent -- npx intentdocs mcp

Or add this to .mcp.json in the repository root:

{
  "mcpServers": {
    "intent": {
      "type": "stdio",
      "command": "npx",
      "args": ["intentdocs", "mcp"]
    }
  }
}

The server finds .intent/config.json by walking up from its working directory, the way git finds .git. Launch Claude Code from inside the repository.

Tool modes

Add --mode to args to shrink the tool list Claude Code keeps in context:

"args": ["intentdocs", "mcp", "--mode", "core"]

core has 7 tools, standard has 12 and all has 15. The default is all. A call to a tool outside the current mode is refused with the mode it needs.

Check it's connected

Ask Claude Code to read intentdocs://project/status. It should return the project's done, in-progress and todo counts. If it doesn't, check that .intent/config.json exists in the directory the server runs from.

If the hosted server refuses the token

A request without a valid token gets 401 with a JSON-RPC error and a WWW-Authenticate header that points at the server's OAuth metadata.

Tokens with the older pb_cli_ prefix still work.