Bullhorn MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with standardized access to the Bullhorn ATS/CRM REST API through BullhornHub authentication.

Features

• 🔐 Secure Authentication: Integrates with BullhornHub's Supabase edge function for credential management
• 🔍 Lucene Search: Full-text search across Bullhorn entities with powerful query syntax
• 📋 Metadata Discovery: Retrieve comprehensive entity schemas, fields, and associations
• ⚡ Session Caching: In-memory caching with 48-hour TTL for optimal performance
• 🛡️ Type-Safe: Full TypeScript implementation with Zod validation

Available Tools

bullhorn_authenticate

Establishes an authenticated session with the Bullhorn API using your BullhornHub API key.

Parameters:

• apiKey (string, optional): Your BullhornHub API key (defaults to BULLHORNHUB_API_KEY environment variable)

Returns:

{
  "BhRestToken": "token_value",
  "restUrl": "https://rest29.bullhornstaffing.com/rest-services/...",
  "dataCenter": "29",
  "expiresAt": 1234567890,
  "environment": "production",
  "cached": false
}

bullhorn_search

Search for Bullhorn entities using Lucene query syntax with pagination and field selection.

Parameters:

• entity (string, required): Entity type (e.g., "Candidate", "JobOrder", "ClientCorporation")
• query (string, required): Lucene search query
• fields (string, optional): Comma-separated list of fields to return (default: "id")
• sort (string, optional): Sort order (prefix with "-" for descending)
• start (number, optional): Starting offset for pagination (default: 0)
• count (number, optional): Number of results to return (max: 500, default: 20)
• apiKey (string, optional): Your BullhornHub API key (defaults to BULLHORNHUB_API_KEY environment variable)

Query Examples:

"firstName:John AND lastName:Doe"
"email:*@example.com"
"status:Active OR status:Pending"
"dateAdded:[20240101 TO 20241231]"
"isDeleted:false"

Returns:

{
  "data": [...],
  "total": 100,
  "start": 0,
  "count": 20,
  "hasMore": true
}

bullhorn_get_entity_meta

Retrieve comprehensive metadata for a Bullhorn entity type.

Parameters:

• entity (string, required): Entity type
• fields (array, optional): Specific field names to retrieve metadata for
• apiKey (string, optional): Your BullhornHub API key (defaults to BULLHORNHUB_API_KEY environment variable)

Returns:

{
  "entity": "Candidate",
  "fields": [
    {
      "name": "firstName",
      "type": "String",
      "dataType": "String",
      "maxLength": 100,
      "required": false,
      "readOnly": false,
      "label": "First Name"
    }
  ],
  "associations": [
    {
      "name": "owner",
      "type": "TO_ONE",
      "associatedEntity": "CorporateUser",
      "editable": true
    }
  ],
  "cached": false
}

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• A BullhornHub API key

Quick Start (Recommended)

Install from npm:

npm install -g @bullhornhub/mcp-server

Then add to your Claude Desktop configuration:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bullhornhub": {
      "command": "npx",
      "args": [
        "@bullhornhub/mcp-server"
      ],
      "env": {
        "BULLHORNHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop and the Bullhorn tools will be available.

Install from Source

1. Clone and install dependencies:

git clone https://github.com/your-org/bullhornhub-mcp.git
cd bullhornhub-mcp
npm install

2. Build the server:

npm run build

3. Configure Claude Desktop:

Add the server to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bullhornhub": {
      "command": "node",
      "args": [
        "/absolute/path/to/bullhornhub-mcp/dist/index.js"
      ],
      "env": {
        "BULLHORNHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

4. Restart Claude Desktop

The Bullhorn tools will now be available in Claude's tool palette.

Production Deployment

Railway (Recommended)

Deploy to Railway for cloud-based AI agents and always-on availability:

# Install Railway CLI
npm install -g @railway/cli

# Login and initialize
railway login
railway init

# Set environment variables
railway variables set BULLHORNHUB_API_KEY="your_api_key_here"
railway variables set NODE_ENV="production"

# Deploy
railway up

Docker

Build and run with Docker:

# Build image
npm run docker:build

# Run container
docker run --rm -it \
  -e BULLHORNHUB_API_KEY=your_api_key_here \
  bullhornhub-mcp:latest

Deployment Modes

The server supports two transport modes:

• stdio (default): For local development and Claude Desktop
• SSE (planned): For HTTP-based streaming in production

See DEPLOYMENT.md for complete deployment instructions including:

• Railway setup and configuration
• Custom domain configuration
• Environment variables
• Monitoring and logs
• Cost estimates
• Troubleshooting

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | BULLHORNHUB_API_KEY | Yes | Your BullhornHub API key | | NODE_ENV | No | Set to production for production deployments | | TRANSPORT_MODE | No | Transport mode: stdio (default) or sse (future) |

Development

Run Tests

npm test

Lint Code

npm run lint

Test with MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Architecture

Project Structure

src/
├── index.ts                 # MCP server entry point
├── tools/                   # Tool implementations
│   ├── authenticate.ts
│   ├── search.ts
│   └── get-entity-meta.ts
├── services/                # Core services
│   ├── bullhorn-client.ts   # HTTP client with retry logic
│   ├── session-cache.ts     # Session management
│   └── metadata-cache.ts    # Metadata caching
├── types/                   # TypeScript definitions
│   ├── bullhorn.ts
│   └── mcp.ts
└── utils/                   # Utility functions
    ├── error-formatter.ts
    └── response-truncator.ts

Key Design Decisions

Authentication:

• Uses Supabase edge function for credential lookup
• Dual-header authentication: apikey (Supabase) + X-API-Key (BullhornHub)
• Sessions cached for 48 hours with automatic expiration

Search:

• POST method with Lucene query in request body
• Query parameters (fields, start, count, sort) in URL
• Response returned directly (no data wrapper)

Metadata:

• GET method with parameters in query string
• Session-linked caching for performance
• Response returned directly from API

Common Entity Types

• Candidate: Job seekers
• JobOrder: Job openings
• ClientCorporation: Client companies
• ClientContact: Client contacts
• Placement: Successful placements
• JobSubmission: Candidate submissions to jobs
• Note: Notes and comments
• Appointment: Calendar appointments

Error Handling

The server provides detailed error messages with suggested actions:

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Error: No authenticated session found\n\nPossible causes:\n- No active authentication session\n- Session expired (older than 48 hours)\n- Invalid API key\n\nSuggested actions:\n- Use bullhorn_authenticate tool to establish a new session\n- Verify BULLHORNHUB_API_KEY is set correctly"
  }]
}

Performance

• Session Caching: 90%+ cache hit rate expected
• Metadata Caching: <100ms response time for cached entities
• Retry Logic: Automatic retry on network errors and 5xx responses
• Timeout: 30-second default timeout with exponential backoff

Security

• API keys never logged or exposed in responses
• Session tokens managed securely in memory
• Supabase edge function handles credential storage
• No persistent storage of sensitive data

License

See LICENSE file for details.

Support

For issues or questions:

• GitHub Issues: [repository-url]/issues
• Documentation: [BullhornHub docs]

Credits

Built with:

• @modelcontextprotocol/sdk
• axios
• zod