Query your pipeline from your own AI

HiringFunnel ships an MCP server (Model Context Protocol) so your AI client — Claude Desktop, Claude Code, Cursor, VS Code, Continue, Zed, or anything else that speaks MCP — can search your job queue, explain why a role was matched, and pull up your saved shortlist without you having to open the dashboard.

Three steps:

1. Issue a Personal Access Token at /dashboard/settings/api.
2. Click the install button for your IDE on that same page (your token is baked in automatically). Or copy the CLI line / JSON block if your client isn't deeplink-aware.
3. Start chatting. Ask your AI about your queue.

Step 1: issue a token

1. Go to /dashboard/settings/api.
2. Give the token a memorable name (e.g. "Claude Desktop on laptop").
3. Click Issue token.
4. Copy the token now. It's shown once. If you lose it, revoke it and issue a new one.

The token is prefixed with pyp_ so it's recognizable in a config file and findable by secret scanners.

Step 2: install HiringFunnel in your client

After you issue a token, four install surfaces appear on the same page. Pick the one that matches your client.

Fastest: one-click install (Cursor, VS Code)

Click Add to Cursor or Add to VS Code. Your browser hands the install URL to the IDE, which adds HiringFunnel to its MCP server list — token and all — automatically. No file editing.

Behind the scenes the button opens a deeplink (cursor://anysphere.cursor-deeplink/mcp/install?... or https://vscode.dev/redirect/mcp/install?...) with your server URL + Authorization header pre-filled.

Claude Code (CLI)

Copy the one-liner from the dashboard. It looks like this:

claude mcp add --transport http hiringfunnel https://api.pypes.dev/mcp --header "Authorization: Bearer pyp_your_token_here"

Paste it into your terminal. claude mcp list will show HiringFunnel in the list.

If you want it in a specific project only, run the command from that project directory (adds to .mcp.json). For a user-wide install, add --scope user.

Claude Desktop / Continue / Zed / other clients

Expand the "Other clients" section on the dashboard and copy the JSON block. It looks like:

{
  "mcpServers": {
    "hiringfunnel": {
      "type": "http",
      "url": "https://api.pypes.dev/mcp",
      "headers": {
        "Authorization": "Bearer pyp_your_token_here"
      }
    }
  }
}

Paste it into your client's config file:

Then restart the client so it picks up the new server.

Security note on install deeplinks

The one-click install buttons pass your token through your operating system to the target IDE. The URL stays local (never leaves your browser), but it does appear in browser history and could be read by a malicious browser extension. If you want to avoid that:

• Issue a token, dismiss the deeplinks, and copy the JSON block instead.
• Or use the Claude Code CLI line in a terminal.

Both paths install the same server — this is a browser-extension / history trade-off, not a server-side difference.

Application order

search_jobs returns rows in application priority order within your own queue:

1. Cards with an application in progress right now (any started_at within the last 10 minutes) pin to the top.
2. Pending and saved rows follow in oldest-queued first order — jobs are applied FIFO within your queue, so the oldest pending row is the next one up.
3. Applied / skipped / dead rows come last as history, newest-completed first.

Two fields in the response help you read the order:

• application_rank — 1-based position within your pending/saved queue. rank: 1 is the next job up. Omitted for applied/skipped/dead rows.
• started_at — RFC3339 timestamp if an application has already been opened on that card. Present only when work is actively in progress.

application_rank reflects within-your-queue order only. Actual wall-clock timing depends on daily application caps and overall system load, so a rank: 1 is not a guarantee of same-day apply.

What you can ask

The server exposes seven tools. Your AI client picks the right one based on your prompt — you don't have to name them.

Scope and safety

• Scope. Tools can read your queue (search, get, similarity, saved) and dismiss queued rows (dismiss_queued_job). They cannot apply on your behalf, change your profile, change your scan config, or touch another member's data. Dismiss is the only mutation — everything else still happens through the web dashboard.
• Scoped to you. Every query is filtered to your member_id. You never see another member's data or the raw global job firehose.
• Untrusted content tagged. Job descriptions scraped from third-party sources are wrapped in <untrusted_data source="..."> tags before they reach your LLM, with zero-width unicode payloads stripped. A hostile listing can't inject instructions into your AI.
• Rate limited. 60 requests per minute per token, with a burst of 10. If you exceed this, the tool returns 429 and the client will back off automatically.
• Revocable. Delete a token from /dashboard/settings/api and the next request 401s immediately.

Troubleshooting

"401 Unauthorized" — Your token is wrong, revoked, or your subscription lapsed. Re-issue from /dashboard/settings/api. The 401 response also carries a WWW-Authenticate header pointing at our OAuth metadata — modern clients will surface this automatically.

"402 Payment Required" — Your subscription is cancelled. MCP access requires an active HiringFunnel membership.

"429 Too Many Requests" — You hit the rate limit. The Retry-After header tells your client when to try again.

Install button opened the wrong app — macOS and Windows ask once which app should handle cursor:// URLs. If you picked the wrong one, reset the handler in your OS settings. VS Code uses an HTTPS redirect so this doesn't apply there.

Install button did nothing — Your IDE isn't installed, or the browser blocked the URL scheme. Fall back to the JSON block in the "Other clients" section.

Tool returns empty results — Not an error. Your queue may not have matches for that query. Try get_scoring_criteria to see what filters are active, and adjust at /dashboard/profile.

Client doesn't see the tools — Restart the client after installing. Some MCP clients cache the tool list at connection time.

Security notes

• Only the SHA-256 hash of your token is stored server-side. A database leak cannot be replayed against /mcp.
• Store the token in your MCP client's config file — same trust boundary as your ~/.ssh/ keys.
• Never paste a pyp_ token into a chat, an issue tracker, or a shared document. If you do, revoke it immediately.
• Rotate tokens periodically. Old tokens don't expire on their own — revoke them when you no longer need them.
• OAuth 2.1 + PKCE is on the roadmap. Until then, Personal Access Tokens are the auth path. If you're a larger team or need token-less auth, let us know.