@c4a/mcp

MCP (Model Context Protocol) Server for C4A knowledge queries. Connects AI coding assistants — Claude Code, Cursor, Windsurf, and any MCP-compatible client — to your indexed codebases and business documents.

What It Does

@c4a/mcp is a thin stdio client that bridges MCP-compatible LLM clients with C4A's REST API. It exposes a single c4a-query tool that accepts natural language queries and returns formatted text results.

┌──────────────────────────────────────┐
│  Claude Code / Cursor / Windsurf     │
│  (LLM Client)                        │
│  ↕ MCP Protocol (stdio)              │
├──────────────────────────────────────┤
│  @c4a/mcp                            │
│  (this package, thin client)         │
│  - c4a-query tool                    │
│  ↕ HTTPS (REST API)                  │
├──────────────────────────────────────┤
│  C4A API Server                      │
│  POST /api/v1/query/ask              │
└──────────────────────────────────────┘

Install

# Run directly (recommended)
npx @c4a/mcp --api-url http://localhost:5100 --api-key c4a_xxx

# Or install globally
npm install -g @c4a/mcp
c4a-mcp --api-url http://localhost:5100 --api-key c4a_xxx

Configuration

Required Parameters

| Parameter | CLI Flag | Environment Variable | Description | |-----------|----------|---------------------|-------------| | API URL | --api-url <url> | API_URL | Base URL of your C4A API server (e.g. http://localhost:5100) | | API Key | --api-key <key> | API_KEY | API key for authentication. Obtain from C4A server admin or via POST /api/v1/auth/test-account/login for local dev |

Priority: CLI flags take precedence over environment variables.

Both parameters are required — the server will exit with an error if either is missing.

Claude Code

Add to your Claude Code MCP configuration (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "c4a": {
      "command": "npx",
      "args": ["@c4a/mcp"],
      "env": {
        "API_URL": "http://localhost:5100",
        "API_KEY": "c4a_xxx",
        "DEBUG": "false"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "c4a": {
      "command": "npx",
      "args": ["@c4a/mcp"],
      "env": {
        "API_URL": "http://localhost:5100",
        "API_KEY": "c4a_xxx",
        "DEBUG": "false"
      }
    }
  }
}

Windsurf / Other MCP Clients

The pattern is the same for any MCP-compatible client — set the command to npx @c4a/mcp and pass the two required environment variables.

Supported Queries

The c4a-query tool automatically classifies your natural language query and routes it to the appropriate API:

| Query Type | Example | |-----------|---------| | Symbol lookup | "Where is validatePayment defined?" | | Reverse tracing | "Who calls validatePayment?" | | Forward tracing | "What does processOrder call?" | | Semantic search | "Code related to payment timeout" | | Structure browse | "Package structure of @c4a/api" |

See the tool description in your MCP client for the full list of supported query patterns and guidelines.

Authentication

The MCP server authenticates with the C4A API using the provided API key via Authorization: Bearer <api_key> header. The key can be either:

• A JWT token — obtained from the login flow
• An API Key (c4a_* prefix) — created via the C4A admin interface

For local development with allow_test_account enabled, you can obtain a token via:

curl -s -X POST http://localhost:5100/api/v1/auth/test-account/login | jq -r .token