@pathmode/mcp-server

Find the product decisions a request leaves open, before your coding agent builds. This server gives your agent check_intent_readiness, a deterministic preflight: six calibrated checks, no model call, the same verdict every run.

No signup and no API key. Specs live in intent.md in your repo, as plain markdown you own.

This repository dogfoods the same workflow: read its intent.md.

See it work

Fieldnote is a small fictional billing app whose ticket FN-412 asks for a Cancel plan button. Given one instruction, implement FN-412, an agent with this server read the ticket and the billing code, found no intent.md, and drafted one instead of code. This is how it explained stopping (recorded 2026-09-25 with the Claude Code plugin 0.1.35 and server 1.34.0; another run may word it differently or find different choices):

FN-412 reads like a one-button change, but it leaves one billing decision open that I don't think I should make for you.

The catch: the only code that cancels a subscription today is revokeAccess (src/billing/access.ts:13). It was written for refunds, and it ends access the moment it's called. If the new button calls it, anyone who cancels loses the rest of a month they've already paid for, with no refund.

It recorded that and three related questions as open product choices, each with a recommendation, the alternative, and what each costs. The verdict on the file it wrote is deterministic, so you can reproduce it:

git clone -b run-4/fn-412-keyless-proposal https://github.com/pathmodeio/fieldnote
cd fieldnote
npx -y @pathmode/cli preflight

Read intent.md at intent.md

  ✓ goal
  ✓ objective
  ✓ outcomes
  ✓ constraints
  ✓ edgeCases
  ✓ verification

✓ Preflight passed. 6/6 checks.
⛔ Not ready to hand to an agent: 4 product choices still unresolved.
  ⛔ When a customer cancels, does access end immediately or at the end of the period they have already paid for?
  ⛔ Does cancelling refund any unused part of the current period?
  ⛔ Can a customer undo a scheduled cancellation before the period ends?
  ⛔ What happens when a past-due (payment failed) customer cancels?
  A recommendation attached to an open choice is an assumption, not a requirement. A person answers or explicitly excludes each one before implementing.

✓ Title  ✓ Objective  ✓ Outcomes  ✓ Constraints  ✓ Edge cases  ✓ Verification

The full run, including every tool call, is in RUN.md.

What a pass means

• Validation (IntentSpec schema) checks structure.
• Preflight checks readiness: a specific title, an objective with an actor and a concrete problem, observable outcomes, a hard constraint, an edge case with its expected behavior, a runnable check, and no open product choice. It reads text against a fixed vocabulary; it cannot tell you the decision is right.
• A person decides each open choice. Until then a recommendation is an assumption, not a requirement. Without a workspace, answer_product_choice records each explicit answer in intent.md, quoted and marked answered locally (unverified). With a connected workspace, the reviewer's answer and their authorization of the exact revision are recorded against their name.
• Verification after the build tests whether the outcomes actually happened.

Quick start

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"]
    }
  }
}

Then ask your agent for a change the way you normally would. The server instructs it to preflight first and, when the repository has no intent.md, to draft one, record the open product choices, and stop before changing code, then to ask you about each open choice and record each answer you give with answer_product_choice. Those are instructions, not enforcement: whether an agent follows them is up to the agent, and the run above is one that stopped. Or draft a spec directly:

> Help me write an intent spec for [your problem here]

That's it. No API key needed.

Sharpen a spec in conversation

The compile-intent prompt turns Claude Code into a Socratic product thinking partner. Describe a problem, paste a support ticket, or explain what's broken — Claude challenges vague thinking, asks pointed questions, runs live quality checks on weak fields, and builds a structured spec.

> Help me write an intent spec for our checkout flow

  What's broken about it? When you say "checkout flow" — is the whole
  thing failing, or is there one specific moment where users bail?

> Payment step times out and users get confused

  When you say "times out" — is that 5 seconds or 30? And what does
  the user actually see? A spinner? A blank screen? An error?

> About 8 seconds, they see a spinner with no feedback

  Proposed Objective: "Reduce cart abandonment caused by payment step
  timeouts exceeding 3 seconds, where users see a spinner with no
  status feedback or recovery path."

  Does that capture it, or is there more to the pain?

When the spec is ready, Claude saves it as intent.md and optionally exports as .cursorrules, CLAUDE.md, or AGENTS.md (Codex/Cursor) — so every AI agent in your project sees the intent as its implementation context.

What You Get

intent.md — Structured spec with YAML frontmatter, written in the open IntentSpec format:

---
id: "intent_17291..."
version: 1
status: "draft"
readiness: "passed 6/6"
---
# Fix Checkout Payment Timeout

## Objective
Reduce cart abandonment caused by payment step
timeouts exceeding 3 seconds.

## Outcomes
- [ ] Payment completes in under 3 seconds (p95)
- [ ] Users see real-time status during processing
- [ ] Failed payments show actionable error with retry

## Edge Cases
- **Network timeout during payment**: Show retry button, no double-charge
- **Unknown provider status**: Hold order, notify user within 30s

The readiness line is the deterministic preflight verdict, stamped on every save — "passed 6/6", or "failed N/6" naming the blocking gates, with "— blocked by N unresolved product choice(s)" appended when a brief's proposed choices still await a human in Pathmode — so any agent reading the file knows whether the spec cleared the gate without re-running it. Specs exported from a Pathmode workspace also carry source: (the canonical intent URL — the file is a working copy of that record) and evidence: (how many linked evidence items back it).

.cursorrules — Agent-directive format for Cursor:

# CURRENT OBJECTIVE
You are implementing: "Fix Checkout Payment Timeout"

# SUCCESS OUTCOMES
Your implementation MUST satisfy ALL of these:
- Payment completes in under 3 seconds (p95)
- Users see real-time status during processing
- Failed payments show actionable error with retry

The optional productChoices frontmatter extension carries durable choice records and their claim IDs. Both MCP and CLI recompute the execution block after reading the file; local saves preserve the records. An older file with a blocked readiness stamp but no records stays blocked via productChoiceReadinessUnknown until refreshed from the source. Connected updates refuse to save if the current choice state cannot be read, leaving both copies unchanged.

CLAUDE.md — Appends a <!-- PATHMODE:START --> section so Claude Code sees the intent in every conversation.

Skill Pack for Claude Code

The package also ships 9 Claude Code skills that auto-trigger based on what you ask — no slash commands required.

| Skill | Use when | |-------|----------| | setup-pathmode-workflow | First-time project setup (test commands, issue tracker, status conventions) | | compile-intent | Building a structured spec for what to ship | | preflight | Running the deterministic six-gate readiness verdict before implementation | | implement-intent | Implementing a repository intent only after Preflight and required human authorization | | verify-intent | Designing the executable feedback loop for a spec | | grill-intent | Stress-testing an existing spec for weaknesses | | split-intent-to-issues | Breaking a spec into Linear / Jira / GitHub Issues tickets | | review-against-intent | Checking code changes against intent outcomes | | handoff-intent | Capturing decisions at end of session |

Install after running the MCP setup:

npx @pathmode/mcp-server install-skills            # project-local (.claude/skills/)
npx @pathmode/mcp-server install-skills --global   # global (~/.claude/skills/)

Restart Claude Code. The skills register at session start and auto-invoke when your request matches their description. See skills/README.md for details.

Local tools

| Tool | Description | |------|-------------| | check_intent_readiness | The deterministic preflight: six calibrated gates, no model call, the same spec always gets the same verdict. With no arguments it resolves the intent.md bound to this repository (at the root, else the single one in intent/); clients that declare no workspace roots (Cursor, Codex, and most programmatic clients) pass repoRoot with the repository's absolute path, and path names one file when intent/ holds several | | confirm_intent_dimension | Resolve a dimension the gate READ but could not confirm (it matches a fixed English and Finnish vocabulary and misses valid phrasing, including other languages), or waive one as not applicable | | answer_product_choice | Record a person's explicit answer to one open product choice in intent.md, or take one back. The accepted claims enter the spec and a decision is logged, exactly as a workspace review would; the answer carries the person's words, is marked answered locally (unverified), and reopens if the choice is edited. A blanket "go with the recommendations" is refused. Keyless mode only | | intent_save | Save an intent spec to the repository's intent.md: the root file, else the single one in intent/, else a new root file | | intent_export | Export as .cursorrules, a CLAUDE.md or AGENTS.md section, or an Outcomes rubric | | intent_import | Adopt an existing OpenSpec change as the intent record; the change folder is never modified |

Local prompt

| Prompt | Description | |--------|-------------| | compile-intent | Start a Socratic conversation to build an intent spec |

Team Features (Workspace Connection Required)

Leave the optional API key empty during installation. When your saved intent.md is ready for team review, use adopt below; you do not need to create a key manually.

Connect a Pathmode workspace when the evidence behind a decision cannot be committed to the repository, when someone outside the repository needs to review and authorize a spec, or when you need to know which intents went stale across repositories.

Adopt an existing repository intent

From a repository containing intent.md with an id, run:

npx @pathmode/mcp-server@latest adopt

Give the printed link and code to the person connecting the repository. In their browser they sign in, select a workspace and Product, review the credential choice, and approve. The agent never creates an account or sends email. No spec content leaves the machine until approval. The approval explains whether the existing machine key is reused, a new key is created, or an explicitly selected key must be replaced. Replacement happens only when the agent collects approval. The machine key is the configured PATHMODE_API_KEY for that API origin or, failing that, a key an earlier adoption on this machine stored for the same origin, so a second repository approved into the same workspace reuses the first one's key instead of replacing it. A key is never presented to an origin it was not stored for. When keys for several workspaces are stored at one origin, the agent-started command presents the most recently stored one, and the pm_adopt_ command tries each.

The command polls for approval for about 100 seconds (--wait=<seconds> changes that budget). If you approve while it is waiting, it collects approval and uploads the spec in that run. Otherwise it exits with AUTHORIZATION_PENDING; ask the agent to run the same command again after approval. The approval request expires after 15 minutes. The pending secret and completion receipt live in ~/.pathmode/pending/ with mode 0600, keyed by the resolved intent file's directory. They never enter repository files. Two commands in the same directory cannot upload concurrently. A failed upload resumes with its saved key and session. Confirmed completion removes the pending secret and extra key copy. Later runs verify the bound record without uploading again; a revoked key or a new intent can start fresh approval. Terminal approval errors clear local pending state; network failures and server errors retain it for recovery.

The existing browser-started flow still works: choose a workspace and Product in repository onboarding, then run npx @pathmode/mcp-server@latest adopt pm_adopt_... with its one-time code. Both entry points upload the existing spec and keep intent.md authoritative.

The safe repository binding lives in .pathmode/config.json and names the workspace and the API origin it was adopted at. The API key lives separately at ~/.pathmode/workspaces/<workspace-id>@<origin>.json, one file per workspace and origin (for example …@https_pathmode.io.json or …@http_localhost_3000.json), so connecting one repository does not repoint other repositories on the same machine, even when a second repository is adopted into the same workspace against a local or staging server. Installs that still hold the older <workspace-id>.json keep working. Add .pathmode/ to .gitignore if your team does not want to commit the non-secret workspace binding.

Prepare a colleague review

The review offer and next-change workflow below need 1.43.3 or later. Update and reconnect your coding client after upgrading.

In connected mode, when a saved proposal has unresolved product choices, the agent is instructed to offer to prepare them for a colleague's review. Tell it who should review; it uses a name you have already supplied rather than making you repeat it. If the offer does not appear, or you are using an older version, ask:

Prepare this change for review. Describe what customers will experience and ask the questions you need answered before building. Attach my original request exactly as written.

After you accept the offer, the agent attaches your original request verbatim, gives you the review link, and starts the review listener if your coding client supports background commands. It should say it is listening only after the listener starts. Share the link with your colleague yourself; Pathmode does not send a reviewer notification. Invite them as an editor if needed; an existing editor needs no new invitation. The colleague needs no API key or terminal.

The reviewer submits answers, the agent applies them, and the reviewer checks and separately approves the resulting revision. Preparing a review or sending answers never authorizes a build. The agent must still pass get_agent_prompt with mode: "execute" before implementing.

Start the next change

A shipped or verified intent remains the record for verification, outcome measurements, and notes about that change. A new product change needs its own proposal and authorization.

When the repository's intent.md is already connected, ask the agent to start a new proposal. It calls intent_save with the complete new spec without an id, localDraft: true, and overwrite: true. This deliberately replaces the active file with a new local draft:

• The previous file, including its cloud identity, is retained byte for byte at .pathmode/retired/intent-<previous-id>.md relative to the original file's folder. Different snapshots get separate filenames; identical copies can be reused. If retention fails, the save is refused. This protects the previous file even if it was never committed.
• The previous hosted intent stays unchanged. The new draft starts at version 1 with a fresh id and no inherited authorization, revision, or sync metadata. The same connected intent cannot be detached by passing its existing id.
• Run adopt for the new draft and approve it in the browser. There is one adoption approval per proposal; a valid existing credential for the same workspace and API origin is reused. This adoption approval is separate from the reviewer's later approval of what may be built.

If adopt exits with AUTHORIZATION_PENDING, rerun the same command after browser approval. Preserve the draft while waiting; a failed upload resumes with its saved key and session. Preflight reports the workspace's shipped or verified status even if the local file's status is older, so an earlier approval cannot be read as permission for the next change.

Workspace API access without a local intent

For an agent or integration that needs workspace tools without adopting a local intent.md, configure an API key:

npx @pathmode/mcp-server@latest setup pm_live_...

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"],
      "env": {
        "PATHMODE_API_KEY": "pm_live_..."
      }
    }
  }
}

Works with Claude Code (.mcp.json in the project root), Claude Desktop (claude_desktop_config.json), and Cursor (.cursor/mcp.json).

Get your API key from Settings > API Keys in the Pathmode app.

Local Mode (Offline)

Local mode is the default when no API key is configured. It reads and writes intent.md in your project directory, and nothing leaves your machine. Local mode includes check_intent_readiness — the deterministic preflight that scores a spec against six calibrated gates and names the exact blockers, with no model call. The same gate, product choices included, runs at preflight.pathmode.io. The plain block is a complete keyless setup:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"]
    }
  }
}

Pass --local only to force local mode when an API key is configured:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server", "--local"]
    }
  }
}

OpenCode (keyless)

Add this to opencode.json in your repository, using OpenCode's local MCP configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pathmode": {
      "type": "local",
      "command": ["npx", "-y", "@pathmode/mcp-server@latest", "--local"],
      "enabled": true
    }
  }
}

Start OpenCode from the repository and ask it to check your intent before implementing. No Pathmode API key, skills, or plugin is required. --local keeps this setup keyless even if you have a workspace key configured elsewhere. The Pathmode preflight itself makes no model or network call; OpenCode's model may still send context to its provider.

Tested with OpenCode 1.19.3 for local intent drafting, readiness checks, request retention, and stopping for unresolved product choices. These instructions guide the agent; they do not enforce a tool or filesystem boundary. Connected workspace authorization is not part of this tested OpenCode path.

Configuration

| Method | Details | |--------|---------| | Environment variable | PATHMODE_API_KEY=pm_live_... | | Repository binding | .pathmode/config.json, with its key stored outside the repo in ~/.pathmode/workspaces/<workspace-id>@<origin>.json | | Config file | ~/.pathmode/config.json with apiKey, apiUrl, workspaceId | | Local mode | Automatic when no key is found. Reads intent.md and .pathmode/intents/*.md; --local forces it | | No config | Local mode. Drafting and preflight need no configuration |

Team Tools

Intent Management

| Tool | Description | |------|-------------| | get_current_intent | Get the active intent (first approved, or most recent) | | get_intent | Get a single intent by ID with full details | | get_intent_evidence | Dereference one intent's repo-safe evidence IDs with trust tiers | | propose_spec_change | Propose an exact, revision-bound correction for a person to accept; stores the observation as unreviewed agent evidence | | list_intents | List all intents, optionally filtered by status | | search_intents | Search intents by keyword across goals, objectives, and outcomes | | create_intent | Create an intent in the workspace without writing a file. Inside a repo prefer intent_save | | update_intent | Update an existing intent's content; pass only the fields you want to change | | update_intent_status | Move an intent through draft > validated > approved > shipped > verified. Not for work delivered by pull request: name the intent on the branch or in the PR body and let the merge grade the real diff and set shipped. Use it for work that never appears in a PR, and for shipped > verified once the outcome is confirmed in production |

PM-to-Repository Change Requests

| Tool | Description | |------|-------------| | list_intent_change_requests | Discover structured PM requests workspace-wide, or narrow to one repository-authority intent; reading records agent consumption | | get_intent_change_request | Read one request with its exact base revision, operation, proposed value, and reason | | reject_intent_change_request | Report an unworkable request with an API-key-attributed reason |

Apply a request by editing intent.md, then call intent_save with both changeRequestId and baseRepoBodyRevision. Pathmode compares immutable snapshots and closes the request itself; an agent cannot submit a success flag or diff.

A decisions request (add, replace, or remove a decision) is applied by the server from the request itself, because an ordinary save only ever adds decisions. intent_save then rewrites the file's decision log from the result. Save it on its own: other body edits in the same save are refused.

When applying a correction, intent_save refreshes a stale version token only if the server's body revision still exactly matches the request's base. A changed body or a concurrent write still stops the save; reading or applying a correction never authorizes implementation.

Delivery & Verification

| Tool | Description | |------|-------------| | verify_implementation | Grade an implementation against the spec by reading the pull request. Pass prUrl and Pathmode fetches the diff itself, grading each outcome, constraint, constitution rule, edge case and verification check against what the code actually shows, with citations. Describing your own work instead is weaker evidence and the result says so | | record_implementation_finding | The spec was wrong: record what it assumed and what building revealed. Targeting a verification check flips that check to failing. Open findings ride into future agent prompts until a human reconciles them | | record_implementation_context | Hand back what the repo actually looks like where this intent lands: files and modules involved, how it behaves today, what a change would risk, how to verify it | | record_outcome_measurement | What actually happened to an outcome after it shipped. The spec said what should change; this says whether it did | | log_implementation_note | The handoff to the next session. The newest notes render into the next agent's execution prompt, so write each one self-contained |

An agent never settles its own delivery. The merge owns the shipped transition for PR-delivered work, and a proposed correction (propose_spec_change) waits for a signed-in person to accept it.

Evidence

| Tool | Description | |------|-------------| | query_evidence | Search evidence items by product, type, severity, or text; returns IDs that can be linked to intents | | create_evidence | Create an evidence item: a discovered bug, a user quote, a behavioral observation, a feature request | | link_evidence | Link or unlink evidence to an intent, establishing traceability between user problems and planned solutions |

Strategic Analysis

| Tool | Description | |------|-------------| | analyze_intent_graph | Analyze dependency graph for critical path, cycles, bottlenecks | | get_intent_relations | Get the dependency graph for a specific intent |

Context & Export

| Tool | Description | |------|-------------| | export_context | Generate CLAUDE.md, AGENTS.md (Codex/modern Cursor), .cursorrules, or intent.md files. For claude-md/agents-md, optionally pass a product ID; for cursorrules/intent-md, product is derived from the resolved intent | | get_agent_prompt | Get a structured execution prompt for an intent | | get_workspace | Get workspace details including strategy, active products, and constitution | | get_constitution | Get mandatory constraint rules for the workspace | | sync_context | Write this workspace's canonical context into the repo's CLAUDE.md or AGENTS.md, idempotently, replacing the PATHMODE-marked section in place |

Team Prompts

| Prompt | Description | |--------|-------------| | implement-intent | Full implementation workflow for a specific intent | | review-risks | Analyze the intent graph for architectural risks | | what-next | Suggest the highest-priority intent to work on next |

Resources

| URI | Description | |-----|-------------| | intent://current | Currently active intent | | intent://graph | Full intent dependency graph | | intent://workspace-strategy | Workspace vision, principles, and active constitution rules |

Reference: how intent.md is found, read, and written

Proto-specs and heading aliases

The Markdown reader accepts ## Problem, then ## Why, as aliases for ## Objective and ## Proposed outcome as an alias for ## Outcomes, including files without YAML frontmatter. The first heading present wins, so a canonical section takes precedence and aliases never merge (IntentSpec SPEC.md section 2). These aliases preserve the author's text; they do not relax readiness requirements. ## What is not an alias, because it usually states the solution rather than an observable result. When outcomes are missing and the file has a ## What section, the verdict says that section was not evaluated and where success criteria belong. A single proposed outcome remains one outcome, and missing edge cases or verification still need attention. An Open questions section does not record resolved product choices or authorization to build.

Which file is read

Repository discovery reads the root intent.md first. When there is none, it reads the single file named intent.md in an intent/ folder (intent/intent.md or intent/<feature>/intent.md), where Anthropic's AI-native SDLC playbook keeps it. Only that name counts, so the spec.md and plan.md committed beside it are never graded as the intent. With several features in intent/, the preflight refuses rather than picking one by folder order; pass path to name the one to check:

check_intent_readiness { "path": "intent/checkout/intent.md" }

intent_save, confirm_intent_dimension, intent_import, and adopt use the same lookup when no path is given, so a save lands in the file the preflight read instead of starting a second intent.md at the root.

Where writes land

Writes land in the server's launch directory, so each write is checked against the repository the preflight resolves from your client's workspace roots, and refuses where the preflight would refuse:

• With no path, the save writes the file the preflight reads, when that file is in the launch directory. An extra workspace folder with no intent does not block it. When several roots each carry an intent.md, pass the absolute path of the one to write.
• An explicit path is refused when the launch directory is not one of the workspace roots, or when the same relative path names an intent in a different root. An absolute path must be inside the launch directory.
• The folder must already exist; a save never creates folders.
• A write never follows a symbolic link out of the repository: an intent.md, a folder, or an exported file (CLAUDE.md, .cursorrules, an OpenSpec change) linked outside is refused.

When a save is refused because the repository differs, restart the MCP server in the repository you are working in.

What a save keeps

A save rewrites the file in Pathmode's format and keeps what no IntentSpec field holds: the text under the title (an Author/Status line) and sections such as ## Affected users and systems or ## Open questions stay, verbatim, and the save lists them. Ownership is never inferred from where a section sits or what it is called. Instead, headings inside field text are nested under the field's section (## Where the contracts live inside Implementation Context is written as ### Where the contracts live, deeper headings shifted with it, fenced code and comments left alone), so every other ## section is the author's. A file written before this keeps such a sub-heading as a ## section; the next save keeps it once and lists it. Custom frontmatter keys are not kept.

Nesting changes the text a reader gets back from the file. It does not change the revision a reviewer authorized, which is computed from the stored fields, but an agent that parses the file and resubmits a field that had ## headings changes that field, and with it the revision, so the spec needs authorizing again.

Alternatively, read the intended file and supply its mapped fields through the MCP tool's inline spec argument. Keep open questions for human review before implementation.

Troubleshooting

The agent is still using an earlier IntentSpec

In keyless mode, first check which repository the client declares as its MCP workspace root. Local read tools and intent://current now resolve those roots on every request, using the server's launch directory only when no usable roots are available. An empty declared root does not fall back to a spec in the launch directory. Listings and search cover all declared roots; current-intent reads refuse to guess between roots containing intents, and a lookup by ID refuses duplicate IDs.

Earlier server builds read local intents from the launch directory even when preflight used a different workspace root. Calling get_intent again could therefore return the wrong checkout's spec. Until using a build containing this fix, launch the server in the working checkout. A client that supplies no workspace roots still needs the correct launch directory.

After confirming the repository, call get_intent again with the intent ID. Connected reads fetch the workspace record on every request. Rerun check_intent_readiness with no arguments to check the repository's current intent.md. In connected mode, that repository file and the workspace record are separate sources: the repository preflight does not substitute the workspace's current intent.

A previous tool result in the conversation is a snapshot. The server does not push changed specs into that result or advertise resource subscriptions; a fresh tool call or resource read is required. Editing a spec does not require restarting the server.

Updating the server software is different: CI passing or building a new bundle does not replace code already loaded by a running process. Install the intended package version (or rebuild the local bundle), verify that the client's MCP configuration points to it, then restart/reconnect that client's Pathmode MCP server. The MCP initialization response reports the running server version. The smoke suite tests fresh reads in a persistent session, but does not certify a particular desktop client's refresh behavior.

"No Pathmode configuration found" This no longer causes an error. Local mode works without any configuration. Team features require an API key.

Team tools are missing from the tool list In local mode the cloud-only tools are not registered, so the agent only sees tools that work. For team review of an existing intent.md, run npx @pathmode/mcp-server@latest adopt from its repository and approve in the browser. For workspace API access without a local intent, configure an API key (setup pm_live_xxx). Restart or reconnect your MCP client after connecting.

Connection timeout Ensure your API key is valid and has the correct scopes. Check your network connection to pathmode.io.

setup starts the server instead of the installer Use the latest package version:

npx @pathmode/mcp-server@latest setup pm_live_...

As a fallback, you can bypass setup entirely by setting the key directly in the MCP config:

{
  "mcpServers": {
    "pathmode": {
      "command": "npx",
      "args": ["@pathmode/mcp-server"],
      "env": {
        "PATHMODE_API_KEY": "pm_live_..."
      }
    }
  }
}

Privacy Policy

This MCP server connects to the Pathmode API (pathmode.io) to read and write intent specifications, workspace data, and constitution rules on behalf of the authenticated user.

Data collected (team features only): The server transmits your API key for authentication and sends/receives workspace data via the Pathmode API. It also reports two usage signals: that a client launched (the client's name and version), and, for each tool that runs, the tool's name and whether it succeeded, including tools such as intent_save that write only to your project. When a tool is refused, the signal names which kind of refusal it was. When the repository has one unambiguous network Git remote, the signal also carries an opaque identifier derived from a hash of that remote, which Pathmode scopes to your workspace before it reaches analytics. The raw remote URL, repository name, local path, tool arguments, spec contents, and file contents are never sent as signals.

Keyless local mode sends nothing. With no API key configured, specs stay in your project directory and the server makes no network request at all: no usage signals and no telemetry of any kind.

Data storage: The MCP server stores intent.md and, when a repository is adopted, a non-secret binding in .pathmode/config.json plus its API key in ~/.pathmode/workspaces/<workspace-id>@<origin>.json. The legacy setup command stores configuration in ~/.pathmode/config.json. Persistent workspace data is stored in Pathmode's cloud infrastructure.

Third-party sharing: No data is shared with third parties. The server communicates exclusively with the Pathmode API.

Full privacy policy: pathmode.io/privacy

Links

• IntentSpec — the open specification for the intent.md files this server writes
• The intent.md profile — the six checks check_intent_readiness scores against
• Preflight — interactive readiness check and local workflow setup
• Pathmode — full platform for teams
• Issues

License

MIT