vanman2024/cats-mcp-server

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 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:

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