MCP (Model Context Protocol)

Audience: Customer — this page documents the Rulecatch MCP server for Claude Code.

Rulecatch provides an MCP Server and MCP API that allow AI assistants to query violation data, rules, and fix plans directly within their context window.

Architecture

The MCP integration consists of two components:

Flow

Claude Code ──MCP Protocol──▶ MCP Server ──HTTP──▶ MCP API ──▶ MongoDB
    (stdio)                    (local)              (remote)

1. Claude Code connects to the MCP Server via stdio
2. User invokes a tool (e.g., rulecatch_violations)
3. MCP Server validates input and calls the MCP API
4. MCP API authenticates the request and queries MongoDB
5. Results flow back to Claude Code's context

Installation

The MCP Server is automatically installed when you run the AI-Pooler init in full mode (with an API key):

npx @rulecatch/ai-pooler init --api-key=dc_your_key_here

This registers both the hooks and the MCP Server in your Claude Code settings. The MCP Server uses the same config as the AI-Pooler (~/.claude/rulecatch/config.json).

The init command adds the following to ~/.claude/settings.json:

{
  "mcpServers": {
    "rulecatch": {
      "command": "node",
      "args": ["~/.claude/rulecatch/mcp-server.js"]
    }
  }
}

Note: The MCP Server is only available in full mode (with an API key). It is not installed in monitor-only mode.

MCP Server

The MCP Server (@rulecatch/mcp-server) runs locally on the developer's machine using stdio transport. It:

• Creates an McpServer instance
• Reads API key from local config
• Initializes an ApiClient for HTTP communication
• Registers 6 tools via registerTools()
• Logs to stderr only (stdout is reserved for JSON-RPC)

Configuration

The MCP Server reads from ~/.claude/rulecatch/config.json:

• apiKey — For authenticating with the MCP API
• region — Determines which MCP API endpoint to use (us → mcp.rulecatch.ai, eu → mcp-eu.rulecatch.ai)

MCP API

A separate Express service (mcp.rulecatch.ai) providing read-only access to Rulecatch data.

Tools

rulecatch_summary

Get a high-level overview of violations and development activity.

Input:

Output:

• Total violations (by severity)
• Correction rate
• Activity metrics (sessions, tokens, cost)

API Endpoint: GET /api/v1/mcp/summary

rulecatch_violations

List violations with optional filters.

Input:

Output:

• List of violations with rule name, severity, file, line, corrected status, timestamp

API Endpoint: GET /api/v1/mcp/violations

rulecatch_violation_detail

Get full details for a specific violation.

Input:

Output:

• Full violation record including matched conditions, event data, and rule details

API Endpoint: GET /api/v1/mcp/violations/{id}

rulecatch_rules

List all active rules for the user.

Input:

No parameters required.

Output:

• List of active rules with name, category, severity, conditions, and enabled status

API Endpoint: GET /api/v1/mcp/rules

rulecatch_fix_plan

Generate a fix plan showing uncorrected violations grouped by file.

Input:

Output:

• Files with violations grouped together
• Each file lists its uncorrected violations
• Violations include rule name, severity, line number, and matched conditions

API Endpoint: GET /api/v1/mcp/fix-plan

rulecatch_top_rules

Get the most frequently violated rules, ranked by count.

Input:

Output:

• Ranked list of most-violated rules with counts, correction rates, percentage of total, and category breakdown

API Endpoint: GET /api/v1/mcp/top-rules

Input Validation

All tool inputs use Zod schemas for validation. Invalid inputs return human-readable error messages.

Response Format

All tools return formatted text responses (not JSON). This is intentional — the output is designed to be readable by AI assistants in their context window:

Violations Summary (Last 7 Days)

Total: 15 violations
  Errors: 3
  Warnings: 8
  Info: 4

Correction Rate: 73%

Activity:
  Sessions: 12
  Cost: $4.52
  Tokens: 1.2M

Error Handling

• Authentication failures return "Invalid or missing API key"
• Network errors return descriptive messages
• All errors are formatted as text content, not thrown exceptions

MCP API Routes

Deployment

The MCP API runs in its own container, separate from the ingest API and dashboard.

Type Definitions

Key types used by the MCP Server:

See Also

• API Overview — Ingest API (separate service)
• Authentication — API key authentication
• Rules and Templates — What rules are available
• Region Isolation — US/EU deployment