MCP Integration Guide

What is SpecBase MCP?

SpecBase exposes its knowledge base through the Model Context Protocol (MCP), allowing AI agents to query which specification documents a project needs, generate starter stubs, and surface best practices — all without leaving your editor.

Two connection modes:

Local Setup (stdio)

Install the specbase binary (install guide), then configure your agent:

Claude Code

Add to your project’s .mcp.json (or ~/.claude/.mcp.json for global):

{
  "mcpServers": {
    "specbase": {
      "command": "specbase",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "specbase": {
      "command": "specbase",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

VS Code (GitHub Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "specbase": {
        "command": "specbase",
        "args": ["mcp", "--transport", "stdio"]
      }
    }
  }
}

Or add a .vscode/mcp.json file to your project:

{
  "servers": {
    "specbase": {
      "command": "specbase",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

Verify it works

Once configured, ask your agent:

“Use the specbase MCP to list all project software types.”

You should see all 11 supported project types.

Remote Setup (mcp.specbase.net)

No installation required. Connect directly to the hosted MCP service.

Claude Code (remote)

{
  "mcpServers": {
    "specbase": {
      "type": "streamable-http",
      "url": "https://mcp.specbase.net/mcp"
    }
  }
}

Cursor (remote)

{
  "mcpServers": {
    "specbase": {
      "url": "https://mcp.specbase.net/mcp"
    }
  }
}

VS Code (remote)

{
  "mcp": {
    "servers": {
      "specbase": {
        "type": "http",
        "url": "https://mcp.specbase.net/mcp"
      }
    }
  }
}

Remote service details

• Endpoint: https://mcp.specbase.net/mcp
• Health check: GET https://mcp.specbase.net/healthz
• Rate limit: 60 requests/minute per IP
• CORS: Open (Access-Control-Allow-Origin: *)
• Auth: None required (public, read-only)
• Privacy: No query logging, no telemetry, no tracking

Available Tools

SpecBase MCP exposes seven tools:

get_standard_docs

Returns the resolved set of specification documents for a project type and optional features.

{
  "type": "web_app",
  "features": ["auth", "payments"]
}

Response includes: document list with titles, priorities, categories, rationale, a generated agent system prompt, and a markdown checklist.

list_software_types

Lists all 11 supported project types with descriptions and feature counts.

{}

list_features

Lists available features for a given project type. For software types with populated metadata (ADR-0021), each feature includes examples (concrete shipped projects that embody the feature) and genre_tags (lowercase taxonomic labels) that let an agent map a natural-language project brief — e.g., “I want a cozy co-op story game” — to the right feature IDs.

{
  "type": "video_game"
}

generate_stubs

Generates starter Markdown file stubs for each resolved document. The server returns file contents — it never writes to disk. Your agent decides where to save them.

{
  "type": "web_app",
  "features": ["auth"],
  "project_name": "my-saas"
}

get_audience_personas

Returns audience personas (market segments served by the software) for a type + feature set, bucketed by tier (required / recommended / optional). Feature selection promotes tier — e.g., adding narrative promotes “Narrative Seeker” from optional to required. Use these to adopt the right end-user perspective when authoring user-facing content.

{
  "type": "video_game",
  "features": ["narrative", "cooperative_multiplayer"]
}

get_team_personas

Returns team personas (job-title archetypes that own documents) for a type + feature set, aggregated across all resolved documents. Each entry lists which documents the persona owns and at what tier. Use these to calibrate vocabulary and depth when generating a specific document.

{
  "type": "video_game",
  "features": ["multiplayer"]
}

Personas are currently seeded for video_game. Software types without persona files return empty results with a note.

specbase_info

Returns a single-call capability snapshot: binary version + commit + build date, negotiated MCP protocol version, KB counts (software types, feature counts per type, which types have persona files), and the full list of registered tools. Use this to version-pin bug reports, detect stale tool caches, or avoid N+1 capability probing.

{}

Response shape:

{
  "version": "v0.1.3",
  "commit": "abc1234",
  "build_date": "2026-04-19T18:04:37Z",
  "protocol": {
    "latest": "2025-06-18",
    "supported": ["2025-06-18", "2025-03-26", "2024-11-05"]
  },
  "kb": {
    "software_types": 11,
    "features_by_software_type": {"video_game": 13, "web_app": 2, "...": 0},
    "audience_persona_types": ["video_game"],
    "team_persona_types": ["video_game"]
  },
  "tools": ["get_standard_docs", "list_software_types", "..."]
}

Example Workflow

Here’s how an agent typically uses SpecBase MCP:

1. Discover project type: Call list_software_types → agent selects video_game

2. Explore features — match user’s intent: Call list_features({type: "video_game"}) → each feature returns examples and genre_tags. The agent maps a brief like “story-driven co-op RPG” to narrative + cooperative_multiplayer by matching genre_tags (story-driven, co-op, cooperative) and comparing examples against the user’s reference points.

3. Get required docs: Call get_standard_docs({type: "video_game", features: ["narrative", "cooperative_multiplayer"]}) → agent receives the full document set with priorities and rationale.

4. Adopt personas when writing: Call get_audience_personas(...) to adopt the end-user voice; call get_team_personas(...) to calibrate document vocabulary.

5. Generate stubs: Call generate_stubs({type: "video_game", features: ["narrative"], project_name: "acme"}) → agent receives Markdown stubs ready to write to disk.

6. Reference documentation: Each document links to its detail page at https://specbase.net/docs/library/<doc-id>/ for deeper guidance.

Tip for CLI users: specbase tree <type> -f <features> renders the whole graph (software type → audience personas → documents → owner personas) in a single terminal view. See the CLI docs for more.

Troubleshooting

“specbase: command not found”

The binary isn’t in your PATH. See the install guide.

Agent doesn’t see SpecBase tools

1. Restart your editor after adding the MCP config.
2. Check that the config file is in the right location for your agent.
3. Verify manually: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | specbase mcp --transport stdio

Remote service returns 429

You’ve hit the rate limit (60 req/min). Wait a moment and retry. The response includes a Retry-After header.

Health check

curl https://mcp.specbase.net/healthz
# → {"status":"ok","version":"..."}

Local vs Remote: Which to Choose?

Recommendation: Use local for daily development. Use remote for quick experiments, CI pipelines, or environments where you can’t install binaries.