MCP Server Integration Guide

Connect Classifyre MCP to Claude, Cursor, Codex CLI, Gemini CLI, Windsurf, VS Code, and custom clients over HTTP.

Connection Details

Every endpoint is scoped to one workspace (namespace): <workspace> is a workspace slug or its immutable UUID, and a client connected to it sees only that workspace’s data. A bare POST /mcp with no workspace returns 404 — connect one client per workspace.

Request Pattern

POST https://<your-host>/<workspace>/mcp
Authorization: Bearer inmcp_<id>.<secret>
Content-Type: application/json

Before You Connect

1. Enable MCP in the dashboard: Settings -> MCP Server -> Enable MCP.
2. Create a token in the same settings page, and choose its tool access: all tools, or only the scopes the client needs.
3. Copy the token immediately. Classifyre returns plaintext only once.

If MCP is disabled, POST /<workspace>/mcp returns 503.

How Tokens Are Created

Classifyre exposes MCP token lifecycle endpoints under <workspace>/instance-settings/mcp/tokens.

Create Token

curl -X POST https://<your-host>/<workspace>/instance-settings/mcp/tokens \
  -H "Content-Type: application/json" \
  -d '{"name":"Cursor local workspace"}'

Response includes:

• plainTextToken: full bearer token (one-time only)
• tokenPreview: masked preview stored for later display
• token metadata (id, name, toolGroupIds, timestamps, active status)

List Tokens

curl https://<your-host>/<workspace>/instance-settings/mcp/tokens

Only masked previews are returned. Raw token values are never returned again.

Revoke / Reactivate Token

curl -X PATCH https://<your-host>/<workspace>/instance-settings/mcp/tokens/<token-id> \
  -H "Content-Type: application/json" \
  -d '{"isActive":false}'

Delete Token

curl -X DELETE https://<your-host>/<workspace>/instance-settings/mcp/tokens/<token-id>

Choose What a Token Can Do (scopes)

Every token has tool access: either all tools, or a list of capability groups (scopes). A client connected with a scoped token sees and can call only the tools of those groups — the rest are left out of tools/list and refused.

In the app: Settings -> MCP Server -> Create token, switch All tools off and tick the groups the client needs. Each group shows how many tools it turns on; hover it to see their names. Edit changes the scope of an existing token; the client picks it up on its next request.

Over the API: send toolGroupIds with the ids from the table below (an unknown id is refused with 400). null or no toolGroupIds means all tools, including groups added in later versions.

curl -X POST https://<your-host>/<workspace>/instance-settings/mcp/tokens \
  -H "Content-Type: application/json" \
  -d '{"name":"Claude, case work","toolGroupIds":["cases","case_board","findings","assets"]}'
 
curl -X PATCH https://<your-host>/<workspace>/instance-settings/mcp/tokens/<token-id> \
  -H "Content-Type: application/json" \
  -d '{"toolGroupIds":["cases","case_board"]}'

Token Format and Validation

• Prefix: inmcp
• Format: inmcp_<uuid>.<secret>
• Secret is generated by the API (crypto.randomBytes(32) in current implementation).
• Tokens are stored hashed (HMAC-SHA256) and verified with constant-time comparison.

Client Configuration

Replace:

• <your-host> with your API host
• <workspace> with the workspace (namespace) slug you want the client to see — the exact URL is shown in Settings -> MCP Server
• inmcp_<id>.<secret> with your token

Claude Desktop

Docs

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "classifyre-mcp": {
      "type": "http",
      "url": "https://<your-host>/<workspace>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

Claude Code

Docs

claude mcp add --transport http classifyre-mcp \
  --url https://<your-host>/<workspace>/mcp \
  --header "Authorization: Bearer inmcp_<id>.<secret>"

Cursor

Docs

{
  "mcpServers": {
    "classifyre-mcp": {
      "type": "http",
      "url": "https://<your-host>/<workspace>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

OpenAI Codex CLI

Docs

~/.codex/config.json (or project codex.json):

{
  "mcpServers": {
    "classifyre-mcp": {
      "type": "http",
      "url": "https://<your-host>/<workspace>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

Run:

codex --mcp-server classifyre-mcp

Gemini CLI

Docs

~/.gemini/settings.json:

{
  "mcpServers": {
    "classifyre-mcp": {
      "httpUrl": "https://<your-host>/<workspace>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

Windsurf (Codeium)

Docs

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "classifyre-mcp": {
      "serverUrl": "https://<your-host>/<workspace>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

VS Code (Copilot)

Docs

.vscode/mcp.json:

{
  "servers": {
    "classifyre-mcp": {
      "type": "http",
      "url": "https://<your-host>/<workspace>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

Continue Extension

Docs

~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "http",
          "url": "https://<your-host>/<workspace>/mcp",
          "headers": {
            "Authorization": "Bearer inmcp_<id>.<secret>"
          }
        }
      }
    ]
  }
}

Direct API Usage

curl -X POST https://<your-host>/<workspace>/mcp \
  -H "Authorization: Bearer inmcp_<id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Classifyre MCP Capability Map

Generated from the tools the server registers (the same source as the tool catalog under Settings -> MCP Server), so it always matches what a client sees. read-only tools never change anything; destructive tools can take things away (clients usually ask before calling them); idempotent tools can be repeated safely. Open a tool for its parameters (* = required).

Resources and prompts

Resources are descriptive and readable with any token.

How To Add New MCP Capabilities

When adding MCP functionality in API code:

1. Register the tool in apps/api/src/mcp-server.factory.ts with a clear description (what it does, when to use it, what it returns), a zod input schema — z.strictObject for anything destructive — and honest annotations (readOnlyHint, destructiveHint, idempotentHint).
2. Put its name in one capability group in apps/api/src/mcp-catalog.ts (or add a group). mcp-catalog.completeness.spec.ts fails on a tool without a group, since a scoped token could never reach it.
3. Destructive tools go in mcp-server.factory.destructive-tools.spec.ts.
4. Run bun run codegen: it regenerates this page’s catalog (apps/docs/src/_generated/mcp-catalog.json); commit it with the change.
5. Validate with tools/list and a tools/call through POST /<workspace>/mcp.

Security Notes

• Never commit tokens.
• Use HTTPS in production.
• Generate one token per client/workspace.
• Rotate by creating a replacement token, then revoke old token.

Troubleshooting

Further Reading

• MCP Specification: modelcontextprotocol.io/specification
• MCP SDKs: modelcontextprotocol.io/sdks
• Anthropic MCP overview: docs.anthropic.com/en/docs/agents-and-tools/mcp