MCP Setup

Overview

Supaspec uses the Model Context Protocol (MCP) to let AI agents read and write specs. There are two connection modes:

• Remote (URL) — for tools that support remote MCP servers (Cursor, Windsurf, Claude.ai, etc.)
• Local (stdio) — for tools that run a local MCP process (Claude Code, etc.)

Prerequisites

• A Supaspec account with an API key (see Getting Started)
• An MCP-compatible AI tool

Remote Connection (Recommended)

For tools that support remote MCP servers, point them at:

https://supaspec.dev/api/mcp

Cursor / Windsurf / Claude.ai

Add this to your MCP configuration:

{
  "mcpServers": {
    "supaspec": {
      "url": "https://supaspec.dev/api/mcp",
      "headers": {
        "x-api-key": "ss_your_api_key_here"
      }
    }
  }
}

Replace ss_your_api_key_here with your actual API key from Settings.

Local Connection (stdio)

For tools that run MCP servers locally via stdio, you can use the @supaspec/mcp-server npm package:

{
  "mcpServers": {
    "supaspec": {
      "command": "npx",
      "args": ["@supaspec/mcp-server"],
      "env": {
        "SUPASPEC_API_KEY": "ss_your_api_key_here",
        "SUPASPEC_URL": "https://supaspec.dev"
      }
    }
  }
}

Claude Code

1. Open or create ~/.claude/mcp.json
2. Paste the local config above
3. Restart Claude Code
4. The agent will self-identify as claude_code on its first write

Codex

1. Open or create ~/.codex/mcp.json
2. Paste the local config above
3. Restart Codex
4. The agent will self-identify as codex on its first write

How Agent Self-Identification Works

The MCP server's tool descriptions include instructions for agents to provide their agent_name on every write call. Agents use a short snake_case identifier like claude_code, cursor, codex, windsurf, or copilot.

This means:

• Zero per-agent configuration — one config, paste it everywhere
• Agents naturally comply — LLMs follow tool parameter descriptions reliably
• New agents work instantly — no config change needed

Verifying the Connection

After setting up, prompt your agent:

"Use supaspec to list my projects."

If the connection is working, the agent will call the list_projects tool and return your project list.

Troubleshooting

"Unauthorized" error: Check that your API key is set correctly and hasn't been revoked.

Agent not appearing in dashboard: Agents are only registered on their first write operation. Read-only operations don't create agent records.