MCP Server (AI Integration)

SpecDown exposes a Model Context Protocol (MCP) server that lets AI assistants read, search, comment on, update, and sync documentation in a structured way.

What is MCP?

The Model Context Protocol is an open standard that lets AI models connect to external systems as structured tools. With SpecDown MCP, an agent can inspect your docs, write updates, upload images, leave review comments, and plan remote sync operations without scraping the UI.

Available Tools

Read & discover

Write & collaborate

Sync planning for agents

Getting an API Key

1. Go to Settings → API Keys.
2. Click Generate new key.
3. Give it a name and choose which projects it can access.
4. Copy the key. It is only shown once.

Two Transports

SpecDown MCP supports both hosted HTTP and local stdio transports.

HTTP + SSE (remote)

Endpoint: https://specdown.app/api/mcp
Protocol: JSON-RPC 2.0 over HTTP + Server-Sent Events
Auth: Authorization: Bearer <your-api-key>

Stdio (local)

npx specdown-mcp --api-key <your-api-key>

Or install globally:

npm install -g specdown-mcp
specdown-mcp --api-key <your-api-key>

Claude Desktop Setup

Add SpecDown to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "your-api-key-here"
      }
    }
  }
}

On macOS, the file is at ~/Library/Application Support/Claude/claude_desktop_config.json.

Typical agent sync flow

The sync tools are designed for agents that already have filesystem access through the host environment.

1. Read local files from the linked folder
2. Hash them into [{ path, hash, documentId? }]
3. Call plan_sync with project_id, remote_prefix, local_files, and optional state_files
4. Review the returned plan and summary
5. Convert approved remote mutations into apply_sync_plan operations
6. Update the local .specdown/sync-state.json after the sync succeeds

Example Prompts

• "Read the authentication docs and summarize the login flow."
• "Search the project for rate limiting and show every matching doc path."
• "Create a new ADR document under /architecture and seed it with a template."
• "Upload this diagram and give me the Markdown to insert into /guides/authentication.md."
• "Plan a sync for my local /docs folder, then show conflicts before applying anything."

Security

All MCP requests are authenticated with a Bearer token. Project access is enforced server-side, so an API key can only access the projects it was issued for.

Write-capable tools such as update_document, add_comment, upload_image, and apply_sync_plan still operate within that same project scope.

Use Cases & Tips

Spec-driven implementation

Write the spec in SpecDown first, then let the AI read and implement against the live source of truth instead of a pasted copy.

AI-assisted review and comments

"Read /api/authentication.md and add review comments for any missing edge cases."

"Compare the new billing doc to the old one and leave comments where breaking changes are unclear."

Agent-managed local mirror

"Read my local linked folder, call plan_sync, and show me what would be pushed."

"Apply only the remote upserts from the approved sync plan, then tell me which files were skipped."

This is the MCP counterpart to the CLI linked-folder workflow. MCP plans and applies remote mutations; the host agent still reads and writes local files.

Backlinks and doc graph exploration

"Show me every document that links to /guides/authentication.md."

"Build a graph for the /architecture subtree and tell me which docs are central hubs."

Use get_backlinks when an agent needs impact-style context before editing a doc, and get_doc_graph when it needs broader relationship awareness across a project area.

Properties and bases-like queries

"List the frontmatter properties for every document under /prd."

"Query the /roadmap subtree for docs where status = draft and tags contains agent."

Use list_properties when an agent needs structured metadata before planning edits, and query_view when it wants a filtered working set instead of scanning every document.

Asset uploads for docs automation

"Upload this PNG to the current project and return the Markdown image link."

"Attach the uploaded image to /guides/onboarding.md and update the document with the returned markdown."

Project attachment automation

"Upload this PDF as /assets/brief.pdf and return the [@/assets/brief.pdf] embed."

"List project files under /assets, read the CSV preview, and summarize the rows."

Use list_project_files, read_project_file, and upload_project_file when agents need to operate on project files. HTML/HTM becomes editable documents; other files remain preview-only assets.

Using with Cursor / Windsurf

# .cursor/mcp.json
{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": { "SPECDOWN_API_KEY": "your-api-key" }
    }
  }
}

Tips & Tricks

• Use project-scoped keys: create separate API keys per project or environment.
• Start with context: call read_project_context or list_documents before deep document reads.
• Search before loading full docs: use search_documents to reduce token usage.
• Use comments for review: prefer add_comment when you want human review instead of directly rewriting a doc.
• Plan sync before apply: treat plan_sync as the safe default and apply_sync_plan as the commit step.
• Use backlinks before rewriting shared docs: call get_backlinks or get_doc_graph first when an edit may affect linked guidance elsewhere.
• Use properties to narrow the search space: call list_properties or query_view before loading every PRD, ADR, or runbook in a large project.
• Pair MCP with the CLI: MCP is excellent for structured agent decisions; the CLI is still the simplest way to keep a real local working copy on disk.