MCP Server¶

The MCP server is the primary integration point for AI assistants. Instead of parsing CLI output, assistants call structured tools that return typed data.

Setup¶

nspec mcp-config

Add the output to your project's .mcp.json:

{
  "mcpServers": {
    "nspec": {
      "command": "nspec",
      "args": ["mcp"]
    }
  }
}

Transport Options¶

stdio (default)¶

Direct pipe, best for local Claude Code:

nspec mcp

SSE¶

For web clients, Docker, or remote access:

nspec mcp --sse        # Listens on http://localhost:8080/sse

HTTP¶

Streamable HTTP transport:

nspec mcp --http       # Listens on http://localhost:8080/mcp

Docker¶

Run the MCP server in Docker with volume-mounted docs:

# Build and start
scripts/mcp-docker.sh start

# With auto-reload on code changes
scripts/mcp-docker.sh watch

# Other commands: stop, restart, logs, status

Configure Claude Code to connect via URL:

{
  "mcpServers": {
    "nspec": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Environment variables: NSPEC_MCP_PORT (default: 8080), NSPEC_MCP_TRANSPORT (sse or http).

Fuzzy ID Resolution¶

All MCP tools accept flexible ID formats:

Full prefixed: S022, E007
Case-insensitive: s022, e7
Bare numbers: 22, 7, 007 — resolved against known specs on disk

Ambiguous bare numbers (where both S### and E### exist) raise an error asking for the full ID.

Test Gate¶

task_complete and criteria_complete run make test-quick before marking items done. Pass run_tests=false to skip.

Sequential Task Enforcement¶

Tasks must be completed in order. Subtasks must be finished before their parent. The MCP server validates this on every task_complete call.

Tool Count¶

nspec exposes 82 MCP tools across query, mutation, checkout, and audit categories. See the Tool Reference for the complete list.

Skills Integration¶

The MCP server works with nspec's skills system — 29 slash commands for Claude Code that orchestrate MCP tool calls into higher-level workflows like /ngo (spec executor) and /nloop (autonomous loop).