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 archetypes.”

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 four 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_archetypes

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

{}

list_features

Lists available features for a given project type.

{
  "type": "web_app"
}

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"
}

Example Workflow

Here’s how an agent typically uses SpecBase MCP:

1. Discover project type: Call list_archetypes → agent selects web_app

2. Explore features: Call list_features({type: "web_app"}) → agent sees auth, payments, realtime, i18n, pwa, analytics

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

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

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

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.