CATS MCP Server

A universal MCP adapter for the CATS (CatsOne) API v3.

Comprehensive, atomic coverage of the CATS API exposed to any MCP-compatible client - Claude, ChatGPT, Codex, Mastra, Google ADK, or your own orchestrator.

For the current inventory see docs/TOOLS.md, generated from the registry.

What a client sees

This server exposes all three MCP primitives, not just tools:

Start with the resource cats://server/capabilities. It states what this server owns, what it deliberately leaves to the caller, and how it is configured - and it works even when CATS is unreachable.

Related MCP server: Viterbit MCP Server

What this is, and is not

This is an adapter. It owns CATS authentication, endpoint coverage, tool schemas, discovery metadata, response shaping, pagination, rate-limit handling and safety classification.

It does not own recruiting workflows, agent orchestration, memory, outreach, scheduling, candidate ranking, or a frontend. Those belong to the calling orchestrator. See docs/ARCHITECTURE.md.

Install

uv venv
uv pip install -r requirements.txt -r requirements-dev.txt
uv pip install -e .

FastMCP 4 is a prerelease, so every dependency is pinned exactly - a loose specifier lets uv resolve that package to a prerelease too.

Configure

Copy the variables you need into .env (gitignored) or set them in your deployment environment.

Run

python server.py                    # stdio, for Claude Desktop / Cursor / Claude Code
CATS_TRANSPORT=http python server.py    # HTTP (requires auth, see below)

Or via the FastMCP CLI:

fastmcp run src/cats_mcp/app.py:mcp

Discovery modes

The catalog is large on purpose - atomic coverage is what makes the adapter reusable. But those schemas must not all land in a model's context.

Every tool stays callable in every mode. Only visibility changes; hidden tools are reached through call_tool, and authorization is enforced the same either way.

Mastra and other orchestrators should use raw and run their own tool search across every connected MCP server. Stacking this server's BM25 transform under Mastra's means searching an index of an index, and prevents Mastra from ranking CATS tools against tools from other servers.

code needs an optional extra:

uv pip install -e '.[code-mode]'

Authentication

Serving over HTTP requires saying who verifies the caller, via CATS_AUTH_MODE. There is no default, because guessing wrong is harmful in both directions: assume a gateway that is not there and destructive tools sit on an open URL; assume none and a correctly-fronted deployment fails to start.

On Horizon, use platform. Its gateway "runs before your server code" and authentication is enabled by default for hosted endpoints, so a rejected caller never reaches this process.

For jwt:

CATS_AUTH_MODE=jwt
CATS_AUTH_JWKS_URI=https://your-issuer/.well-known/jwks.json
CATS_AUTH_ISSUER=https://your-issuer/
CATS_AUTH_AUDIENCE=cats-mcp

stdio needs no mode - the transport is a pipe to a process you started.

Per-tool scopes (cats:read, cats:write, cats:destructive, cats:bulk, cats:admin) apply in jwt mode, where this server sees verified claims. Authorization then filters discovery as well as execution: a read-only caller cannot see destructive tools in a listing, in search results, or reach them through call_tool. Under platform, the gateway authenticates but this server sees no claims, so authorization is the gateway's to enforce.

Working with candidate data

List and search tools return compact summaries by default - ids plus a small field projection, with count, total, has_more and next_page.

Widen deliberately:

Custom fields are where account-specific screening data lives, so reach for summary_level='standard' rather than fetching each candidate individually - that is the difference between one request and fifty against a 500/hour budget.

Links back to CATS

Set CATS_UI_BASE_URL and every record carries a url field pointing at it in the CATS web UI. Consumers were otherwise building these by hand and getting them wrong - CATS uses index.php?m=candidates&a=show&candidateID=..., not a REST-style /candidates/{id} path, so hand-built links look right in a spreadsheet and 404 when clicked.

Unset, no link is emitted at all. A missing link is recoverable; a wrong one is not noticed until someone tries to use it.

Resumes, attachments, activities, pipelines and applications are never included in a list at any level. They are unbounded in size and each has its own tool - download_attachment returns the actual document for the model to read.

Rate limits

The CATS standard is 500 requests/hour. Some accounts are raised, so the real ceiling is read from the response headers rather than assumed; Retry-After is honoured and backoff is jittered.

Call get_connection_status to see the remaining budget before a large batch.

The composite read primitives exist for this reason - get_candidate_engagement answers "when was each of these 50 candidates last contacted" in one tool call instead of 50, and returns a compact table instead of 50 activity lists. See docs/TOOLS.md.

Development

python -m pytest tests/ -q            # test suite
python -m ruff check src/ tests/      # lint
python scripts/generate_tool_docs.py --write   # regenerate docs/TOOLS.md

Tool counts are generated from the registry and a test fails if the docs drift.

Adding a tool

Tools are declarative. Add a ToolSpec to the right module in src/cats_mcp/registry/specs/ - name, endpoint, method, parameters and their locations, safety class, tags and response strategy. One executor turns any spec into a working tool; there is no per-tool request code to write.

Documentation

Superseded documentation is not kept in the working tree; git history has it.