MCP Server Integration Guide

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

Connection Details

Request Pattern

POST https://<your-host>/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.
3. Copy the token immediately. Classifyre returns plaintext only once.

If MCP is disabled, POST /mcp returns 503.

How Tokens Are Created

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

Create Token

curl -X POST https://<your-host>/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, timestamps, active status)

List Tokens

curl https://<your-host>/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>/instance-settings/mcp/tokens/<token-id> \
  -H "Content-Type: application/json" \
  -d '{"isActive":false}'

Delete Token

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

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
• 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>/mcp",
      "headers": {
        "Authorization": "Bearer inmcp_<id>.<secret>"
      }
    }
  }
}

Claude Code

Docs

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

Cursor

Docs

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

Windsurf (Codeium)

Docs

~/.codeium/windsurf/mcp_config.json:

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

VS Code (Copilot)

Docs

.vscode/mcp.json:

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

Continue Extension

Docs

~/.continue/config.json:

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

Direct API Usage

curl -X POST https://<your-host>/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

This section is documented from apps/api/src/mcp-catalog.ts and no longer shown in the Settings UI.

Sources

• Description: Create, validate, update, delete, inspect, and run ingestion sources.
• Tools: search_sources, get_source, create_source, update_source, delete_source, test_source_connection, start_source_run
• Operations:
  • Search and filter sources
  • Validate source configs against JSON Schema before save
  • Start connection tests and runs

Custom Detectors

• Description: Manage regex, classifier, and entity detectors and train them on feedback.
• Tools: list_custom_detectors, get_custom_detector, list_custom_detector_examples, create_custom_detector, update_custom_detector, delete_custom_detector, train_custom_detector, get_custom_detector_training_history
• Operations:
  • Create detectors for rulesets, classifiers, and entities
  • Inspect starter examples before authoring a detector
  • Trigger training and inspect training history

Runs

• Description: Inspect ingestion runs, stop stuck runs, and fetch logs for debugging.
• Tools: search_runs, get_run, get_run_logs, stop_run, list_source_runs
• Operations:
  • Search runs across the instance or by source
  • Read paginated runner logs
  • Stop long-running jobs

Findings

• Description: Search, inspect, and update findings including bulk status changes.
• Tools: search_findings, get_finding, update_finding, bulk_update_findings, get_findings_discovery
• Operations:
  • Search and filter findings by status, severity, type, and text
  • Resolve or reopen findings
  • Summarize discovery totals for MCP clients

Assets

• Description: Inspect assets, search asset inventory, and link findings back to content.
• Tools: search_assets, get_asset, list_source_assets, list_asset_finding_summaries
• Operations:
  • Search assets with nested finding filters
  • Inspect a single asset
  • Browse asset-level finding summaries

Prompt Helpers

• brainstorm_custom_detector
  • Title: Brainstorm Custom Detector
  • Description: Guide an MCP client to propose regex, classifier, or entity detector configs before training.

How To Add New MCP Capabilities

When adding new MCP functionality in API code:

1. Update apps/api/src/mcp-catalog.ts with the new capability group and tool names.
2. Register tool handlers in apps/api/src/mcp-server.factory.ts.
3. Implement execution logic in apps/api/src/mcp-tool-executor.service.ts.
4. If needed, expose supporting API endpoints and DTO updates.
5. Validate by calling tools/list and the new tool through POST /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