Developer & MCP

Use the HADEF 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

The MCP server process is defined in the repo under hadef_mcp/ (stdio transport). It is not the same as this site’s OpenAPI browser at /docs (Swagger UI).

Connect

Set the API base URL and key in the environment used by the MCP server (for example in your project .env):

HADEF_API_URL=http://localhost:8000
HADEF_API_KEY=your_api_key_here

Alternatively, HADEF_DEV_API_KEY is read if HADEF_API_KEY is unset. Every HTTP request from MCP to the API sends:

Header: X-API-Key: <your key>
Header: Content-Type: application/json

Endpoint URL: the value of HADEF_API_URL (production example: https://your-api.example.com). MCP tools map to REST paths such as POST /prospect, GET /prospects, GET /prospect/{id}/pitch, and so on.

Quick start

  1. Create an API key in Hadef and set HADEF_API_URL and HADEF_API_KEY for the MCP process.
  2. Run the MCP server (stdio) and register it with your client (e.g. Claude Desktop config pointing at python hadef_mcp/server.py or your packaged command).
  3. Call research_prospect with name, company, and LinkedIn URL; poll check_status until the pipeline finishes; then get_pitch (or get_research earlier in the run).

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": "Chief Communications Officer",
  "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_research

Get research results: sources, sufficiency flag, assessment, and episode concept summary when available.

Example arguments
{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Example response (abbreviated)
{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sources_found": 6,
  "sufficient_for_pitch": true,
  "assessment": "Strong traditional sources with recent appearances.",
  "recommended_angle": "Decision tension between brand narrative and operational reality.",
  "sources": [
    {
      "title": "Episode: Leading Through Disruption",
      "url": "https://example.com/ep/42",
      "type": "podcast",
      "date": "2025-08-01",
      "summary": "Discusses stakeholder alignment and measurement."
    }
  ],
  "concept": {
    "title": "When the Narrative Meets the Numbers",
    "premise": "…",
    "hook_quote": "…",
    "hook_source_url": "https://…",
    "editorial_lens": "decision_quality",
    "unexplored_thread": "…"
  }
}

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": "Chief Communications Officer",
      "status": "researched"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Sam Rivera",
      "company": "Contoso",
      "title": "VP Communications",
      "status": "new"
    }
  ]
}

approve_pitch

Approve a pitch for sending: marks the prospect as sent after you have reviewed the package.

Example arguments
{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Example response
{
  "prospect_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "new_status": "sent",
  "message": "Pitch approved and marked as sent."
}

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