@firestitch/specify-mcp

MCP server for AI agents to interact with Specify's project management features.

Prerequisites

• Node.js >= 18

Install from npm

npm install @firestitch/specify-mcp --save-dev

Then point Cursor at the package binary (see below). prepublishOnly runs npm run build, so the published tarball includes dist/.

Template: copy mcp.json.example to .cursor/mcp.json in your project (or merge the specify entry into your existing file). It uses @firestitch/specify-mcp@latest so npx targets the newest published version; set SPECIFY_API_* in your shell or system environment (Cursor interpolates ${env:…}).

Monorepo / clone setup

cd mcp
npm install
npm run build

Default transport is stdio (no SPECIFY_TRANSPORT env). The editor runs the server on your machine; put Specify URL + API keys in the same MCP config as env (see below). Paths resolve from the workspace cwd.

After successful auth (stdio only), the server applies a one-time workspace init: ensures .specify/, merges .vscode/settings.json (open **/.specify/**/*.md in markdown preview, set markdown.mermaid.enabled if unset), and merges .vscode/extensions.json with bierner.markdown-mermaid recommended. Set SPECIFY_MCP_SKIP_WORKSPACE_INIT=1 to disable. Remote HTTP MCP does not run this on the developer’s laptop.

Set SPECIFY_TRANSPORT=http when you want a standalone HTTP server (local dev below, or hosting behind nginx).

Running

Development — watches for changes and auto-reloads an HTTP server on http://localhost:3100 (scripts set SPECIFY_TRANSPORT=http):

| Command | API URL | |---------|---------| | npm run serve:local | http://specify.local.firestitch.com/api/ | | npm run serve:development | https://specify.firestitch.dev/api/ | | npm run serve:staging | https://specify.staging.firestitch.com/api/ | | npm run serve:production | https://fs.specify.com/api/ |

Production — builds once and runs the compiled output as HTTP on port 3100:

| Command | API URL | |---------|---------| | npm run start:staging | https://specify.staging.firestitch.com/api/ | | npm run start:production | https://fs.specify.com/api/ |

For those HTTP modes, clients send credentials with X-Api-Key and X-Api-Secret on each connection. Generate keys from Account > API Keys in Specify.

Connect your editor (stdio — recommended)

One config file: put the server command and Specify credentials together (Cursor: .cursor/mcp.json). Credentials are only read from environment variables set by the client (SPECIFY_API_*); there is no credentials.json file.

Installed package + node_modules path:

{
  "mcpServers": {
    "specify": {
      "command": "node",
      "args": ["node_modules/@firestitch/specify-mcp/dist/index.js"],
      "env": {
        "SPECIFY_API_URL": "https://your-instance.example.com/api/",
        "SPECIFY_API_KEY": "your-api-key",
        "SPECIFY_API_SECRET": "your-api-secret"
      }
    }
  }
}

npx (no local install) — use @latest on the package so the requested version is always the newest tag on npm (still subject to npm/npx cache; run npx clear-npx-cache if an old build sticks):

{
  "mcpServers": {
    "specify": {
      "command": "npx",
      "args": ["-y", "--package", "@firestitch/specify-mcp@latest", "specify-mcp"],
      "env": {
        "SPECIFY_API_URL": "https://your-instance.example.com/api/",
        "SPECIFY_API_KEY": "your-api-key",
        "SPECIFY_API_SECRET": "your-api-secret"
      }
    }
  }
}

Or keep secrets out of the file with Cursor interpolation (same pattern as mcp.json.example):

"env": {
  "SPECIFY_API_URL": "${env:SPECIFY_API_URL}",
  "SPECIFY_API_KEY": "${env:SPECIFY_API_KEY}",
  "SPECIFY_API_SECRET": "${env:SPECIFY_API_SECRET}"
}

Use an absolute path in args if the package lives outside the project. Paths like "${workspaceFolder}/node_modules/..." work in args per Cursor docs.

Claude Code (stdio example):

claude mcp add --transport stdio specify -- node /path/to/specify/mcp/dist/index.js

HTTP transport (local testing or hosted)

Point the client at the server URL and pass headers (stdio env is not used for HTTP):

Cursor

{
  "mcpServers": {
    "specify": {
      "url": "http://localhost:3100",
      "headers": {
        "X-Api-Key": "your-api-key",
        "X-Api-Secret": "your-api-secret"
      }
    }
  }
}

Claude Code

claude mcp add --transport http specify http://localhost:3100 \
  --header "X-Api-Key: your-api-key" \
  --header "X-Api-Secret: your-api-secret"

Remote / hosted HTTP server

Hosted deployments must run with SPECIFY_TRANSPORT=http. Clients use the public origin (no /api/ path in the MCP URL unless your proxy is configured that way):

{
  "mcpServers": {
    "specify": {
      "url": "https://specify.staging.firestitch.com",
      "headers": {
        "X-Api-Key": "your-api-key",
        "X-Api-Secret": "your-api-secret"
      }
    }
  }
}

Architecture

src/
  index.ts              Entry point, transport selection, tool registration
  workspace-init.ts     Local .specify/ + .vscode merge (stdio after auth)
  transport/http.ts     Express + StreamableHTTPServerTransport
  api/client.ts         HTTP client with Bearer token auth
  auth/session.ts       Authentication manager
  config/
    credentials.ts      SPECIFY_API_* env (from MCP client)
    project.ts          .specify.json auto-detection
  state/session.ts      Session state (project, plan, task)
  guides/loader.ts      Loads markdown guides for learning tools
  tools/                One module per domain + discovery, guidance, selection
  resources/            MCP Resources (browsable project data)
  prompts/              MCP Prompts (workflow templates)
  validation/           Input validation and field aliasing
guides/                 Domain documentation loaded at runtime

Domains, prompts, and resources are self-documented by the MCP server. Use specify_list_domains to discover available domains and their tools.