developer docs

hireburst mcp server.

Connect hiring agents to the hireburst MCP 2.1 contract for role plans, target maps, interview loops, scorecards, and after-interview calibration. This developer surface supports MCP only.

Read the contract Generate API token
MCP 2.1 JSON-RPC envelopes with hireburst tool schemas and explicit authorization failures.
OAuth Remote agent connections use the OAuth-protected MCP endpoint at hireburst.com/api/mcp.
Bearer Server-side MCP clients can mirror the same calls with tokens from /manage/api-keys.
Endpoint

Remote MCP endpoint

The public contract is exposed at https://hireburst.com/api/mcp. Remote MCP clients should treat it as an OAuth-protected MCP 2.1 resource. The server advertises protected resource metadata and responds with WWW-Authenticate whenever authorization is missing, expired, or invalid.

POST https://hireburst.com/api/mcp Authorization: Bearer <oauth_access_token> Content-Type: application/json Resource metadata: https://hireburst.com/.well-known/oauth-protected-resource/api/mcp 
{
  "jsonrpc": "2.0",
  "id": "hb-init-01",
  "method": "initialize",
  "params": {
    "protocolVersion": "2.1",
    "clientInfo": {
      "name": "your-agent",
      "version": "1.0.0"
    }
  }
}
Capabilities

Supported MCP tools

The MCP surface is intentionally narrow. Each tool returns hiring-system artifacts that can be reviewed by humans before any candidate-facing action happens.

hireburst.role_plan.create Create a first-pass role plan with target thesis, interview loop, scorecard, and learning plan.
hireburst.targeting.map Map candidate archetypes, adjacent markets, source channels, and outreach priorities.
hireburst.interview_loop.design Design structured interview rounds, evidence prompts, and scorecard anchors.
hireburst.calibration.update Update the next targeting and interview move from new interview evidence without changing the bar.
Schema

Example tool call

Tool calls use JSON-RPC 2.0 envelopes with MCP 2.1 tool names. Inputs are compact, role-first, and designed for hiring teams that already have an operating context.

{
  "jsonrpc": "2.0",
  "id": "hb-call-42",
  "method": "tools/call",
  "params": {
    "name": "hireburst.role_plan.create",
    "arguments": {
      "company": "BlockHome AI",
      "role": "Account Manager",
      "team_size": 34,
      "growth_goal": "scale customer organization before enterprise expansion",
      "must_have_signals": [
        "real estate workflow fluency",
        "adoption-risk saves",
        "expansion judgment",
        "product feedback synthesis"
      ]
    }
  }
}

Until the workspace identity is connected, the production endpoint rejects every request at authorization time and does not run tools.

OAuth discovery is available at https://hireburst.com/.well-known/oauth-authorization-server. The current token endpoint fails closed with invalid_client until workspace authorization is enabled.

Current response

Authorization failures

The MCP endpoint currently fails closed. Expect 401 Unauthorized, a standards-shaped WWW-Authenticate header, and a JSON-RPC error payload.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="hireburst-mcp",
  error="invalid_token",
  resource_metadata="https://hireburst.com/.well-known/oauth-protected-resource/api/mcp"

{
  "jsonrpc": "2.0",
  "id": "hb-call-42",
  "error": {
    "code": -32001,
    "message": "Authorization failed",
    "data": {
      "mcp_version": "2.1",
      "authorization": "oauth"
    }
  }
}
Bearer mirror

Bearer-token MCP calls

For server-side clients that do not run the OAuth browser connection, mirror the same MCP calls at https://hireburst.com/api/mcp/bearer with a bearer token. Generate tokens at hireburst.com/manage/api-keys.

POST https://hireburst.com/api/mcp/bearer Authorization: Bearer hb_live_... Content-Type: application/json

Bearer calls expose the same tools, schemas, and error model as the OAuth endpoint. Invalid, missing, or unavailable tokens always receive 401 until API key management is enabled.