Bullhorn MCP Agent
# Bullhorn MCP Agent
A Python Model Context Protocol (MCP) server for Bullhorn, extended into a recruiting-domain operating layer for AI agents and enterprise workflows.
This project began from the open-source `osherai/bullhorn-mcp-python` project and has been substantially expanded with tenant-aware schema mapping, per-user Bullhorn authentication, controlled writes, recruiting activity models, audit and approval controls, and agent-oriented workflow tooling.
The goal is to provide a governed layer between AI systems and Bullhorn rather than giving a model direct access to credentials, unrestricted REST endpoints, or tenant-specific business logic.
---
## Current Status
This project is currently in active **POC and test-stage development**.
It is not yet distributed for production use.
The current focus is validating:
- authentication and session isolation
- tenant configuration and mapping
- permission boundaries
- recruiting-domain semantics
- safe read/write patterns
- auditability
- security controls
- historical analytics architecture
- enterprise Workspace integration
Bullhorn remains the system of record.
---
## What This Project Is Becoming
This is no longer just a thin REST wrapper around Bullhorn.
The MCP is being developed as a recruiting-domain operating layer that sits between AI systems and Bullhorn.
Its responsibilities include:
- authenticating users
- isolating Bullhorn sessions
- enforcing permissions
- translating canonical recruiting concepts into tenant-specific Bullhorn fields
- validating workflows
- controlling writes
- auditing actions
- exposing structured recruiting data
- supporting analytics and historical intelligence
- keeping the model away from raw credentials and unrestricted API access
Conceptually:
```text
ChatGPT Workspace / AI Agent
|
| MCP
v
Bullhorn Recruiting Orchestrator
|
|-- Authentication / session isolation
|-- Permissions
|-- Tenant mappings
|-- Canonical recruiting schema
|-- Safe reads
|-- Controlled writes
|-- Approval gates
|-- Audit
|-- Activity / analytics
|
| Bullhorn REST API
v
Bullhorn
```
---
## License
License: Source-available for self-use, internal organizational use, modification, forking, and open development. Resale, white-labeling, commercial packaging, or offering the software itself as a paid hosted service requires prior express written permission. Portions derived from upstream MIT-licensed projects remain subject to their original licenses.
See [`LICENSE`](LICENSE) (CaseyTTS Source-Available No-Resale License 1.0) and [`THIRD_PARTY_LICENSES/`](THIRD_PARTY_LICENSES/) for the preserved upstream MIT License of `osherai/bullhorn-mcp-python`. This license is not an OSI-approved open-source license.
TDQS
Scored across 23 tools
There is substantial overlap between the generic search tools (search_entities Lucene, query_entities SQL-like, find_records structured filters) and the specific ones (list_jobs, list_candidates, get_recent_placements), so an agent can easily pick the wrong path to the same data. get_notes versus get_activity (which includes note_created) and connection_status versus setup_status versus bullhorn_session also blur together. The very detailed descriptions do help differentiate them, keeping this from being worse than a 3.
Most tools follow a verb_noun snake_case pattern (list_jobs, get_candidate, propose_mapping_changes, confirm_write), which is readable and predictable. However several tools break the pattern with noun or non-standard verb forms (connection_status, setup_status, bullhorn_session, manage_mapping_profile). The mix is understandable but not fully consistent.
23 tools is on the heavy side and sits in the borderline range where redundancy costs appear. The breadth (CRM reads, mapping-profile governance, safe-write pipeline, activity and metrics) justifies many tools, but the generic search trio overlaps with the resource-specific list tools, suggesting some could be consolidated.
The server has strong read coverage (jobs, candidates, placements, notes, activity, metrics) and a well-governed write path, but it lacks create/update for the core CRM entities (no candidate/job/submission/placement creation). For a Bullhorn agent the only real writes are notes and resume upload, a notable lifecycle gap.