Developer & MCP

Use the Hadef AI MCP server from Claude Desktop, Cursor, or any MCP-capable client. The server is a thin layer over the Hadef REST API: same authentication and the same six tools.

What the MCP server is

Hadef ships a Model Context Protocol (MCP) server that exposes the guest-research pipeline as callable tools. Your AI assistant can start research, poll status, pull research and pitch payloads, list prospects, and approve a pitch without using the web dashboard. Under the hood, the MCP process calls your Hadef API over HTTP with an API key.

For AI agents

/llms.txt, short public index for LLMs
/llms-full.txt, full orientation and source excerpts
/.well-known/agent.json, agent card (capabilities and tools)

Two ways to connect: a hosted MCP endpoint for cloud agents and marketplaces, and a local stdio server for desktop clients. Both use the same tools. The REST reference is at /docs/api; the raw OpenAPI browser (Swagger UI) is at /docs/api.

Get an API key

Generate a key below (you must be signed in), or from Settings → API. It is shown once and looks like hdk_…. The same key authenticates the hosted MCP endpoint and the REST API. Usage draws down your account’s credit balance; top up or upgrade in Settings.

Your API keys

Connect: hosted MCP (recommended)

Point any Streamable-HTTP MCP client at:

URL:    https://hadef.io/mcp
Header: Authorization: Bearer hdk_<your key>

The endpoint speaks JSON-RPC 2.0. Discovery calls (initialize, tools/list, ping) need no key; tools/call requires your key and spends credits for billable tools (for example mark_pitch_sent). The tool set is published at /.well-known/mcp/server-card.json.

curl -s https://hadef.io/mcp \
  -H "Authorization: Bearer hdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"research_prospect",
                 "arguments":{"linkedin_url":"https://linkedin.com/in/example"}}}'

Connect: local stdio server (Claude Desktop, Cursor)

For desktop clients that launch a local MCP process, set the API base URL and key in the environment used by the MCP server (for example in your project .env):

HADEF_API_URL=https://hadef.io
HADEF_API_KEY=hdk_your_key_here

The local server sends X-API-Key: <your key> on each request. The hosted endpoint above is the recommended path for cloud agents and marketplace listings.

Quick start

Create an API key in Hadef and set HADEF_API_URL and HADEF_API_KEY for the MCP process.
Run the MCP server (stdio) and register it with your client, pointing the client at the packaged command we send you with your key.
Call research_prospect with name, company, and LinkedIn URL; poll check_status until the pipeline finishes; then get_pitch.

Tools

Each tool name is what MCP clients use in tools/call. Arguments are JSON. Responses are JSON strings returned as MCP text content (pretty-printed in examples below).

`research_prospect`

Start research on a guest: creates the prospect and triggers the full pipeline (research, transcripts, concept, pitch, QA). Returns immediately with a prospect_id; poll check_status for completion.

Example arguments

{
  "name": "Jordan Lee",
  "title": "VP of Marketing",
  "company": "Northwind Labs",
  "linkedin_url": "https://www.linkedin.com/in/jordanlee"
}

Example response

{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Jordan Lee",
  "company": "Northwind Labs",
  "pipeline_status": "started",
  "message": "Pipeline started.",
  "next_step": "Use check_status with prospect_id 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' to monitor progress."
}

`check_status`

Check pipeline progress for a prospect: running state, whether research and pitch exist, and QA flag.

Example arguments

{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example response

{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "prospect_name": "Jordan Lee",
  "overall_status": "researched",
  "pipeline_running": false,
  "pipeline_status": "completed",
  "has_research": true,
  "has_pitch": true,
  "qa_passed": true,
  "message": "Pipeline complete. Use get_pitch to retrieve the pitch package."
}

`get_pitch`

Get the completed pitch package: LinkedIn message, email subject and body, concept title, hook quote, and QA result.

Example arguments

{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example response (abbreviated)

{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "prospect_name": "Jordan Lee",
  "concept_title": "When the Narrative Meets the Numbers",
  "hook_quote": "We stopped optimizing for applause and started optimizing for outcomes.",
  "linkedin_message": "… full message 200–280 words …",
  "word_count_linkedin": 246,
  "email_subject": "Your podcast,  conversation on narrative vs. operational truth",
  "email_body": "… full body …",
  "word_count_email": 310,
  "qa_passed": true,
  "qa_result": { "QA_PASSED": true, "quote_verified": true }
}

`list_prospects`

List all prospects with id, name, company, title, and status.

Example arguments

{}

Example response

{
  "total": 2,
  "prospects": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jordan Lee",
      "company": "Northwind Labs",
      "title": "VP of Marketing",
      "status": "researched"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Sam Rivera",
      "company": "Contoso",
      "title": "VP Engineering",
      "status": "new"
    }
  ]
}

OpenAPI / Swagger UI for raw REST routes: /docs. Explainer for answer engines: What is Hadef?