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

Candidate and job records carry a url field pointing at them 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.

The domain is derived, not configured. GET /site returns the account's subdomain, and which account that is follows from the API key, so the adapter reads it from the same credential it is already using - once per account, cached for the process, and skipped entirely for the tools that can never emit a link. That is what keeps links correct if different callers bring different CATS accounts: a single configured value would hand one of them links into the other company's CATS. Set CATS_UI_BASE_URL only to override - a vanity domain, or to avoid the lookup.

A link is only emitted where the id genuinely identifies that record. A tool is tagged with the resource it belongs to, not the shape of the rows it returns, so list_candidate_attachments is a candidate tool returning attachments - building a candidate link from an attachment id yields a working link to an unrelated real person, which returns 200 and so is never reported as an error. Saved-list membership rows are the one exception that still links: the row names its candidate in candidate_id, so the link is built from that, never the row's own id.

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.

Known gap: attachment uploads are unverified

upload_candidate_attachment sends file_url in a JSON body. Nobody has confirmed that against a live account, and CATS's documented endpoint (POST /candidates/{id}/attachments?filename=..., filename as a query param) reads like a binary upload, not a fetch-this-url request - the same kind of never-tried spec that create_task and create_candidate_work_history turned out to be. Fix only after a live attempt produces a real error to fix against; do not guess the shape. See issue #25.

That issue also tracks the planned use of this tool: a standalone script, outside this repo, that watches a local downloads folder for LinkedIn profile PDF exports, extracts the profile URL printed in the document, and resolves the candidate via lookup_candidate's exact profile_urls match - never by name. An unresolved or ambiguous match is left for a human; nothing here guesses which candidate a loose file belongs to. This adapter owns no filesystem access or scheduling by design (see "What this is, and is not" above), so that script runs locally on its own schedule and calls this server, rather than living in src/cats_mcp/.

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.