CATS MCP Server

FastMCP server for CATS (Complete Applicant Tracking System) API v3 with dynamic toolset loading.

Overview

This MCP server provides access to 228 tools across 17 toolsets covering the complete CATS API v3. The toolset architecture allows agents to load only what they need, optimizing token usage and performance.

Key Features:

🎯 228 MCP tools covering all CATS API v3 endpoints (complete coverage)
📦 17 toolsets organized by resource type
⚡ Dynamic loading - load only what you need
🔐 Secure - token-based authentication, no hardcoded credentials
📝 Type-safe - full type hints on all tools
📚 Well-documented - comprehensive docstrings with examples
🚀 Production-ready - error handling, async/await, tested
☁️ FastMCP Cloud ready - automatic deployments from GitHub
📊 Monitoring - health checks and structured logging

Quick Start

Option 1: FastMCP Cloud (Recommended)

Deploy to managed cloud with automatic GitHub deployments:

# 1. Ensure fastmcp.json exists (already created)
# 2. Push to GitHub
# 3. Create project at https://fastmcp.app
# 4. Set CATS_API_KEY environment variable
# 5. Deploy automatically - done!

# Access at: https://your-project-name.fastmcp.app/mcp

See FASTMCP_CLOUD_DEPLOYMENT.md for complete guide.

Option 2: Local Development

# 1. Install dependencies
pip install fastmcp httpx python-dotenv

# 2. Configure
cp .env.example .env
# Edit .env with your CATS_API_KEY

# 3. Run
python server.py --list-toolsets  # See available toolsets
python server.py                  # Load default toolsets (89 tools)
python server.py --toolsets all   # Load all 162 tools

Architecture

Toolset Organization

DEFAULT Toolsets (105 tools) - Loaded by default:

candidates (44 tools) - Complete candidate management + all sub-resources
jobs (35 tools) - Complete job management, lists, applications, statuses
pipelines (17 tools) - Pipeline workflows and status management
context (3 tools) - Site info, user info, authorization
tasks (5 tools) - Task management

RECRUITING Toolsets (106 tools) - Optional:

companies (48 tools) - Complete company management + phones, departments, lists, statuses, thumbnails
contacts (42 tools) - Complete contact management + lists, statuses, thumbnails
activities (6 tools) - Activity tracking (calls, meetings, emails)
portals (8 tools) - Career portals and applications
work_history (3 tools) - Employment history management

DATA & CONFIG Toolsets (22 tools) - Optional:

tags (2 tools) - Global tag management
webhooks (4 tools) - Webhook subscriptions with 24+ event types
users (2 tools) - User and permissions management
triggers (2 tools) - Automated trigger information
attachments (4 tools) - File management + AI resume parsing
backups (3 tools) - Database backup management
events (5 tools) - Calendar events and scheduling

Token Efficiency

Agents load only needed toolsets, dramatically reducing token usage:

Toolsets	Tools Loaded	Use Case
Default	105 (~46%)	Core recruiting
candidates,companies	92 (~40%)	Candidate sourcing
all	228 (100%)	Complete API coverage

Installation

1. Setup

# Clone repository
cd cats-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install fastmcp httpx python-dotenv

2. Configure

Create .env file:

CATS_API_BASE_URL=https://api.catsone.com/v3
CATS_API_KEY=your_cats_api_key_here

# Optional: Default toolsets
CATS_TOOLSETS=candidates,jobs,companies

3. Add to Claude Desktop

Edit ~/.claude/config.json:

{
  "mcpServers": {
    "cats": {
      "command": "python",
      "args": ["/path/to/cats-mcp-server/server.py"],
      "env": {
        "CATS_API_BASE_URL": "https://api.catsone.com/v3",
        "CATS_API_KEY": "your_api_key",
        "CATS_TOOLSETS": "candidates,jobs,companies"
      }
    }
  }
}

Usage

Command Line

# List toolsets
python server.py --list-toolsets

# Default (77 tools)
python server.py

# Specific toolsets
python server.py --toolsets candidates,jobs,companies

# Everything (163 tools)
python server.py --toolsets all

# Environment variable
export CATS_TOOLSETS='candidates,pipelines'
python server.py

Common Combinations

# Recruiting team
--toolsets candidates,jobs,pipelines,companies,activities

# Hiring manager
--toolsets candidates,jobs,pipelines,events

# Administrator
--toolsets users,webhooks,backups,triggers,tags

# Full access
--toolsets all

API Coverage

Complete Tool List

Candidates (44 tools) - Complete Coverage

Main: list, get, create, update, delete, search, filter, authorize
Sub-resources: pipelines, activities, attachments, custom fields (with details), emails (full CRUD), phones (full CRUD), tags, work history (full CRUD), lists (full CRUD), thumbnails

Jobs (35 tools) - Complete Coverage

Main: list, get, create, update, delete, search, filter
Sub-resources: activities, attachments, custom fields (with details), tags, statuses (full management)
Job lists: full CRUD + item management
Applications: list, get details, get fields

Pipelines (17 tools) - Complete Coverage

Main: list, get, create, update, delete, filter
Workflows: list workflows, get workflow, list workflow statuses, get workflow status
Status management: get history, change status

Companies (48 tools) - Complete Coverage

Main: list, get, create, update, delete, search, filter
Sub-resources: activities, attachments, contacts, custom fields (with details), pipelines, tags
Advanced: phones (full CRUD), departments (full CRUD), lists (full CRUD), statuses, thumbnails

Contacts (42 tools) - Complete Coverage

Main: list, get, create, update, delete, search, filter
Sub-resources: activities, attachments, custom fields (with details), emails (full CRUD), phones (full CRUD), pipelines, tags
Advanced: lists (full CRUD), statuses, thumbnails

Activities (6 tools)

list, get, update, delete, search, filter
Types: email, meeting, call_talked, call_lvm, call_missed, text_message, other

Portals (8 tools)

list, get, list jobs
submit application, publish/unpublish jobs
registration forms

Work History (3 tools)

get, update, delete

Tags (2 tools)

list, get

Webhooks (4 tools)

list, get, create, delete
24+ event types with HMAC-SHA256 verification

Users (2 tools)

list, get
Access levels: read_only, edit, admin

Triggers (2 tools)

list, get

Attachments (4 tools)

get, delete, download
parse_resume - AI-powered resume parsing

Backups (3 tools)

list, get, create
Options: attachments, emails

Events (5 tools)

Full CRUD: list, get, create, update, delete
Attendees, virtual meeting URLs, calendar integration

Context (3 tools)

get_site, get_me, authorize_user

Tasks (5 tools)

Full CRUD with priority, assignments, due dates

Development

File Structure

cats-mcp-server/
├── server.py                  # Core (242 lines)
├── toolsets_default.py        # Default (1,611 lines, 77 tools)
├── toolsets_recruiting.py     # Recruiting (1,364 lines, 64 tools)
├── toolsets_data.py           # Data (1,017 lines, 22 tools)
├── .env                       # Config (not in git)
├── .env.example               # Template
├── README.md                  # This file
└── cats-v3-api-endpoints.md   # API reference

Testing

# Syntax check
python -m py_compile server.py toolsets_*.py

# List toolsets
python server.py --list-toolsets

# Test loading
python server.py --toolsets candidates

Troubleshooting

Common Issues

"CATS_API_KEY not configured"

Set in .env or export as environment variable

"Module not found: toolsets_*"

Ensure all three toolset files exist

Rate Limiting (500 req/hour)

Monitor X-Rate-Limit-Remaining header
Implement backoff on 429 errors

401 Unauthorized

Verify API v3 key (not v2)
Check key permissions

Resources

CATS API: https://docs.catsone.com/api/v3/
FastMCP: https://gofastmcp.com/
MCP Protocol: https://modelcontextprotocol.io/

License

Provided as-is for CATS API v3 integration. Follow CATS API terms of service.

Changelog

2025-12-16 - v2.0.0

Complete API coverage: Expanded from 164 to 228 tools (+64 endpoints)
Added missing critical features:
- Lists management (candidate/job/company/contact lists - 32 endpoints)
- Status management (job/company/contact statuses - 9 endpoints)
- Thumbnails (candidate/company/contact - 6 endpoints)
- Custom field details (3 endpoints per resource - 9 total)
- Work history CRUD (3 endpoints)
- Company phones (5 endpoints)
- Company departments (5 endpoints)
Bug fixes:
- Fixed filter_candidates pagination (moved to JSON body)
- Fixed filter_jobs pagination (moved to JSON body)
Now covers 100% of documented CATS API v3 endpoints

2025-01-26 - v1.0.0

Initial release with toolset architecture
164 tools across 17 toolsets
Dynamic loading via CLI/environment
~82% CATS API v3 coverage
Production-ready