betterspec serve

Start the betterspec MCP (Model Context Protocol) server. This exposes your project's specs, knowledge, and capabilities as tools and resources that AI coding assistants can access natively.

Usage

betterspec serve [options]

You can also start the server via npx:

npx @betterspec/mcp

Options

Option	Description
`-C, --cwd <path>`	Run as if betterspec was started in the given path

How it works

The MCP server runs as a stdio-based process that AI tools connect to. It provides structured access to your betterspec project without the AI needing to read raw files from disk.

Connecting to AI Tools

Claude Code

claude mcp add betterspec -- npx @betterspec/mcp

OpenCode

Add to your OpenCode MCP configuration:

{
  "betterspec": {
    "command": "npx",
    "args": ["@betterspec/mcp"]
  }
}

Gemini CLI

Add to your Gemini CLI settings:

{
  "mcpServers": {
    "betterspec": {
      "command": "npx",
      "args": ["@betterspec/mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "betterspec": {
      "command": "npx",
      "args": ["@betterspec/mcp"]
    }
  }
}

Available Tools

The MCP server exposes 10 tools:

Read

Tool	Description
`betterspec_status`	Get project status — active changes, capabilities count, task completion
`betterspec_list`	List changes with optional status filter and archived flag
`betterspec_show`	Return all spec files for a change (proposal, requirements, scenarios, design, tasks)
`betterspec_search`	Keyword search across specs and capabilities
`betterspec_impact`	Show what specs and capabilities reference a file or path
`betterspec_digest`	Get a summary of project knowledge — capabilities, active changes, configuration
`betterspec_diff`	Run drift analysis and return the drift report

Write

Tool	Description
`betterspec_propose`	Create a new change proposal
`betterspec_verify`	Check spec completeness (structural)
`betterspec_archive`	Archive a completed change and capture knowledge

Available Resources

The MCP server exposes 6 resources:

Resource	Description
`betterspec://config`	Current project configuration
`betterspec://changes`	List of all active changes with metadata
`betterspec://change/{slug}`	Full spec set for a specific change
`betterspec://knowledge`	All knowledge documents
`betterspec://capabilities`	All registered capabilities
`betterspec://skills`	Available skill definitions

AI tools use these resources to load context on demand rather than scanning the filesystem.

betterspec serve

On this page