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 5 tools:

Tool	Description
`betterspec_status`	Get the current project status dashboard
`betterspec_propose`	Create a new change proposal
`betterspec_verify`	Verify a change against its specs
`betterspec_search`	Search the project knowledge base
`betterspec_impact`	Analyze the impact of changing a file

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