Skip to main content
Agent integrations · MCP

Use HeadHonta from any compatible agent interface

HeadHonta exposes a remote Model Context Protocol server for agent clients, IDEs, internal assistants, and custom orchestration systems. It is a standards-based integration, not a ChatGPT-only feature.

Connect an agent

  1. 1

    Authenticate

    Use delegated OAuth for public clients or a scoped key for a private integration.

  2. 2

    Configure the client

    Use Streamable HTTP, the MCP URL, and a Bearer authorization header.

  3. 3

    Verify tools

    The client discovers only tools allowed by the key's scopes.

MCP endpoint

https://head-honta-production.up.railway.app/api/v1/mcp

Generic client configuration

{
  "name": "headhonta",
  "transport": "streamable-http",
  "url": "https://head-honta-production.up.railway.app/api/v1/mcp",
  "headers": {
    "Authorization": "Bearer <HEADHONTA_API_KEY>"
  }
}

Client configuration formats vary. The universal values are the Streamable HTTP endpoint andAuthorization: Bearer …. Never paste a live key into documentation, support tickets, or source control.

Available tools

Tool discovery is filtered by credential scope and server-side operational controls.

list_jobsjobs:readList accessible jobs
get_jobjobs:readRead a job and its requirements
search_candidatescandidates:readSearch the organization talent pool
get_candidatecandidates:readRead an accessible candidate profile
list_candidatescandidates:readList organization candidates
list_pipeline_stagespipeline:readRead configured pipeline stages
get_candidate_pipelinepipeline:readRead a candidate's current stage
list_interviewsinterviews:readList accessible interviews with minimized personal data
get_interviewinterviews:readRead an accessible interview without transcripts or raw CVs
list_sequencessequences:readList communication sequence definitions
get_sequencesequences:readRead a communication sequence definition
list_job_publicationspublishing:readRead job publication status

Human-approved write proposals

When write tools are enabled by the HeadHonta operator, agents can propose these changes but cannot approve them.

propose_create_jobjobs:writePropose a draft job
propose_move_candidatepipeline:writePropose a candidate pipeline move
propose_create_pipeline_stagepipeline:writePropose a pipeline stage

Authentication and isolation

  • Every request requires a revocable, scoped credential.
  • The key is bound to its creator and organization.
  • Active membership and job-level permissions are rechecked.
  • Organization IDs supplied by agents are never trusted.
  • Revoking the key stops subsequent requests.

Private and public connections

Scoped API keys support private workspace and developer integrations. OAuth 2.1 with PKCE supports public, multi-user, and one-click connections without sharing a workspace key.

How write actions work

Write tools create expiring action proposals instead of mutating hiring data immediately. A named user reviews the exact change, approves it, and HeadHonta executes it once with a complete audit trail.

pending
approved
executing
executed
failed

High-impact actions such as rejection, outbound communication, offers, and final hiring decisions will always retain stronger human approval requirements.