MCP Server - HeyMilo AI Documentation

HeyMilo hosts a Model Context Protocol (MCP) server at https://mcp.heymilo.ai/mcp. Any MCP-compatible client can connect to it and let users query HeyMilo with natural language (search candidates, summarize pipelines, pull interview reports) without writing custom integration code. The server is read-only. It exposes the same data surfaces an authenticated user can see in app.heymilo.ai, scoped to whichever HeyMilo workspaces the authenticated identity has access to. To create postings, ingest candidates, or modify workflows, call the corresponding REST endpoint on https://api.heymilo.ai directly. The milo_capabilities MCP prompt describes every write endpoint with curl examples your LLM can read and recommend.

What you can ask

“Who are my top 10 candidates for the Senior Backend Engineer role?”
“Summarize last month’s interviews: completion rate, average score, decisions.”
“What’s the candidate pipeline for the Atlanta Sales Lead position?”
“Pull the interview report for int_abc123.”
“How do I create a new interviewer?” (load the milo_capabilities prompt first, see Available tools, then the LLM will hand you a ready-to-paste curl example)

Authentication

The server accepts two auth methods, both passed as Authorization: Bearer <token>:

Method	Best for	Notes
Sign in with HeyMilo (OAuth 2.1)	claude.ai, Claude Desktop, Cursor, ChatGPT, Google Antigravity (anywhere a user is at the keyboard)	Standard OAuth flow; the token is tied to a HeyMilo user and grants access to every workspace they’re a member of
API key	Programmatic clients, scripts, server-to-server agents	Single shared key per workspace, no expiry; one key = one workspace

Recommended for end-user clients. The MCP client discovers the OAuth flow automatically via https://mcp.heymilo.ai/.well-known/oauth-authorization-server, then redirects through the HeyMilo login screen. After sign-in, the client receives access and refresh tokens tied to that HeyMilo user.

claude.ai

Settings → Connectors → Add custom connector.
Server URL: https://mcp.heymilo.ai/mcp.
Connect. claude.ai walks you through the HeyMilo login.
The connector lights up; HeyMilo tools appear in any new chat’s tools menu.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "heymilo": {
      "url": "https://mcp.heymilo.ai/mcp"
    }
  }
}

Quit and reopen Claude Desktop. On first connect it discovers OAuth, runs the HeyMilo login flow, and persists the token.

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "heymilo": {
      "url": "https://mcp.heymilo.ai/mcp"
    }
  }
}

Claude Code

Add the server to ~/.claude.json (or run claude mcp add):

{
  "mcpServers": {
    "heymilo": {
      "type": "http",
      "url": "https://mcp.heymilo.ai/mcp"
    }
  }
}

Restart Claude Code, then run /mcp → heymilo → Authenticate to complete the HeyMilo login. Claude Code (like other native CLI clients) uses an ephemeral loopback port for its OAuth callback; the server handles this automatically, with no per-port configuration needed.

ChatGPT

ChatGPT can connect to remote MCP servers like HeyMilo, but only through developer mode, which exposes full MCP connector support. Developer mode is available on Plus, Pro, Business, Enterprise, and Education plans (web), and ChatGPT only supports remote MCP servers reachable over HTTPS — which is exactly what HeyMilo hosts.

Enable developer mode. In ChatGPT, go to Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
Add the connector. Back in Settings → Apps & Connectors, choose Create (create app / add custom connector) and fill in:
- Name: HeyMilo
- MCP Server URL: https://mcp.heymilo.ai/mcp
- Authentication: OAuth
Check the box confirming you trust the provider, then create the connector.
ChatGPT discovers the OAuth flow automatically (the server supports OAuth metadata discovery and dynamic client registration) and walks you through the HeyMilo login. After sign-in, the HeyMilo tools are available in chat — open the + / Developer mode tools menu and enable them for a conversation.

Google Antigravity (Gemini)

Google Antigravity shares a single MCP configuration across its IDE and CLI at ~/.gemini/config/mcp_config.json. You can edit that file directly or use the in-app Manage MCP Servers → View raw config editor.

{
  "mcpServers": {
    "heymilo": {
      "serverUrl": "https://mcp.heymilo.ai/mcp"
    }
  }
}

To authenticate, open Agent Settings → Customizations, click Authenticate next to heymilo, complete the HeyMilo login in your browser, then copy the authorization code back into the settings panel and click Submit. Antigravity registers itself with the server via dynamic client registration, so no client ID or secret is needed.

Use the serverUrl key for remote HTTP servers (the older httpUrl key is deprecated). To connect with an API key instead of OAuth, add a headers block: "headers": { "Authorization": "Bearer YOUR_HEYMILO_API_KEY" }.

API key

Use this for non-interactive clients (scripts, server-to-server agents) where there isn’t a human to walk through OAuth.

In app.heymilo.ai, Integrations → API, generate a key.
Pass it as a Bearer token (or in the legacy X-API-KEY header):

curl -X POST https://mcp.heymilo.ai/mcp/ \
  -H "Authorization: Bearer YOUR_HEYMILO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The MCP endpoint is /mcp/ (with a trailing slash). A request to /mcp returns a 307 redirect to /mcp/; standards-compliant MCP clients follow it automatically (a 307 preserves the method, body, and Authorization header), so the https://mcp.heymilo.ai/mcp URL in the config blocks above works as-is. For raw HTTP tooling like curl, target /mcp/ directly (as above) or add -L to follow the redirect. Otherwise the request stops at the 307 and returns nothing.

Claude Desktop and Cursor accept API keys directly in the config block:

{
  "mcpServers": {
    "heymilo": {
      "url": "https://mcp.heymilo.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_HEYMILO_API_KEY" }
    }
  }
}

An API key has full read access to your workspace’s data. Treat it like a password. Rotate any time under Integrations → API.

Multi-workspace access

Some HeyMilo users belong to more than one workspace. When you sign in via OAuth, the resulting token covers every active workspace the user is a member of. All tools accept an optional workspace_id argument:

Omit it → the tool defaults to your “primary” / first-listed workspace.
Pass it explicitly → scopes the call to that specific workspace.

To discover what’s accessible, call the listWorkspaces tool. The LLM can also use it implicitly: when a user asks about “Acme”, the model calls listWorkspaces, finds the matching workspace_id, and includes it in the next tool call. API-key auth is single-workspace by definition: one key = one workspace, and workspace_id is fixed.

Available tools

Every tool is read-only. Apart from listWorkspaces (a custom tool that takes no arguments), the set is generated directly from the Public API v2 GET endpoints — so it always matches what the API exposes — and each generated tool accepts the optional workspace_id argument described above.

Area	Tools
Workspaces	`listWorkspaces`
Postings (jobs)	`listPostings`, `getPosting`, `getPostingStats`
Candidates	`listCandidates`
Interviews	`getInterviewData`, `getInterviewMetadata`
Interview templates	`listInterviewTemplates`, `getInterviewTemplate`
Questions	`listQuestions`, `getQuestion`
Voices	`listVoices`, `getVoice`, `getVoicePreview`
Email	`listSenderEmails`, `getSenderEmail`, `listEmailTemplates`, `getEmailTemplate`, `listEmailTemplateGroups`, `getEmailTemplateGroup`
Design templates	`listDesignTemplates`, `getDesignTemplate`, `listDesignTemplateGroups`, `getDesignTemplateGroup`
Phone numbers	`listPhoneNumbers`, `getPhoneNumber`
Domains	`listDomains`, `getDomain`
Webhooks	`listWebhooks`, `getWebhook`
Schema / metadata	`list_agent_types_api_v2_schemas_agents_get`, `list_question_types_api_v2_schemas_question_types_get`

To enumerate them programmatically, call the MCP tools/list method (see the API-key curl example above). Write endpoints (create posting, ingest candidate, archive, etc.) are not callable as MCP tools. To help LLMs guide users through writes, the server exposes a prompt named milo_capabilities (and a matching milo://capabilities resource) that returns a structured description of the full v2 surface, including writes, with curl examples and links back to this documentation.

To explore everything the HeyMilo API can do, browse the Public API documentation, or invoke the /mcp__heymilo__milo_capabilities prompt from your MCP client for the full catalogue with ready-to-run curl examples.

Discovery endpoints

For programmatic clients building against the server:

Endpoint	Purpose
`GET /.well-known/oauth-authorization-server`	RFC 8414 authorization-server metadata
`GET /.well-known/oauth-protected-resource`	RFC 9728 protected-resource metadata
`POST /oauth/register`	RFC 7591 dynamic client registration
`GET /oauth/authorize`	OAuth authorization endpoint (redirects to the identity provider)
`GET /oauth/callback`	Identity-provider redirect target; forwards the auth code back to the client’s redirect URI (handled automatically; clients never call this directly)
`POST /oauth/token`	OAuth token endpoint (proxied to the identity provider)
`POST /mcp/`	MCP JSON-RPC endpoint (Streamable HTTP transport). `/mcp` `307`-redirects here
`GET /healthz`	Liveness probe

Unauthenticated requests to /mcp respond with

WWW-Authenticate: Bearer realm="mcp.heymilo.ai", resource_metadata="https://mcp.heymilo.ai/.well-known/oauth-protected-resource"

so clients can discover OAuth on first contact.

Security model

Per-request authorization. Every /mcp request re-validates the token. For OAuth, the user’s workspace memberships are re-checked against our datastore and cached briefly (a few minutes), so revoked access propagates within that window.
Strict workspace scoping. A user can only call tools with workspace_id values present in their token’s accessible workspaces. Tool calls server-side scope every database query by workspace_id.
Tokens are short-lived. Access and refresh token lifetimes are enforced by HeyMilo’s identity provider, and refresh tokens can be rotated on use.
All HTTPS, all the time. TLS via managed certificates.

Troubleshooting

Claude doesn't see any HeyMilo tools

Check that your config is valid JSON and restart your client fully (Cmd-Q on macOS). The tools panel in any chat should list listPostings, getInterviewData, etc.

`401` or `403` when calling tools

A 401 means missing or expired credentials. For OAuth, your access token may have expired — disconnect and reconnect from your client’s connector settings. An invalid or revoked API key returns 403; generate a new one in app.heymilo.ai → Integrations → API.

Tool call says 'workspace_id is not in your accessible workspaces'

The LLM passed a workspace_id you don’t have access to. Have it call listWorkspaces first to see what’s available, then retry with one of those IDs.

Tool calls hang or time out

Searches over very large candidate pools can take up to 60 seconds. Increase your client’s tool-call timeout if you’re hitting limits.

​What you can ask

​Authentication

​Sign in with HeyMilo (OAuth)

​claude.ai

​Claude Desktop

​Cursor

​Claude Code

​ChatGPT

​Google Antigravity (Gemini)

​API key

​Multi-workspace access

​Available tools

​Discovery endpoints

​Security model

​Troubleshooting

What you can ask

Authentication

Sign in with HeyMilo (OAuth)

claude.ai

Claude Desktop

Cursor

Claude Code

ChatGPT

Google Antigravity (Gemini)

API key

Multi-workspace access

Available tools

Discovery endpoints

Security model

Troubleshooting