This article is also available in:

Umamy MCP

Umamy MCP


Connect Claude, ChatGPT, and other AI tools to your Umamy hunts via MCP. Query candidates, search messages, get hunt analytics, and act on your sourcing pipeline from your favourite AI assistants.


Connect your AI tools to your Umamy account with Umamy MCP. Once connected you can use this to: browse your hunts and their configuration, search through your candidates, read conversations and notes, get analytics across your sourcing funnel, and answer questions about your pipeline — directly from inside Claude, ChatGPT, or any other AI tool that supports MCP.


We currently only support authentication through browser OAuth. For programmatic, server-to-server access (e.g. from a backend you control), use API keys with the Umamy customer API instead.


Beta: Umamy MCP is generally available to test. Availability and features may change as we iterate.


Set-up guide


Pre-requisites


  • A Umamy account with at least one hunt
  • An AI tool that supports MCP, such as Claude or ChatGPT


You'll need a paid Claude or ChatGPT account to add custom MCP connectors. See below for the specific tiers.


How to connect


Claude


Custom connectors are only available on paid Claude plans. On Team or Enterprise plans, your workspace admin may need to approve custom connectors or connect Umamy for you.


  1. Open and sign in to Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector and paste https://api.umamy.io/mcp as the server URL.
  4. Click Connect, sign in with your Umamy account in the browser window that opens, and authorize the connection.
  5. Make sure the Umamy connector is toggled on when chatting.


ChatGPT


ChatGPT custom connectors are only available on Plus, Pro, Business, or Enterprise plans.


  1. Open and sign in to ChatGPT.
  2. Go to Settings → Connectors.
  3. Click Add MCP server and paste https://api.umamy.io/mcp.
  4. Authorize the connection in the browser window that opens.
  5. You can now reference Umamy in ChatGPT — for example, ask "summarise my latest hunt" and ChatGPT will call the Umamy MCP tools.


Claude Code


  1. Run claude in your terminal.
  2. Add the connector:


   claude mcp add umamy --transport http https://api.umamy.io/mcp


  1. Open a new terminal tab and run claude again.
  2. Run /mcp, select umamy, and choose Authenticate.
  3. Sign in with your Umamy account in the browser window that opens, then ask Claude to reference your hunts.


Other AI tools


You can manually connect to the Umamy MCP server by using the public URL https://api.umamy.io/mcp as a custom connection.


Your AI tool must support:


  • MCP client protocol using Streamable HTTP transport.
  • OAuth 2.0 authentication — the server uses browser-based OAuth, so your tool needs to be able to open a browser window for the user to sign in to Umamy. After sign-in, the tool receives a bearer token to include in subsequent requests.


Each user authenticates individually through the browser OAuth flow. There is no API key or service account access for MCP — see the Umamy customer API for that use case.


Tools and descriptions


Tool

Description

Example prompt

list_organizations

Lists every Umamy organization you belong to. Always the entry point — use the returned organization_id for every other call.

"Which Umamy organizations am I in?"

list_hunts

Lists hunts in an organization with status, candidate counts, and key configuration. Filter by status (DRAFT / LIVE / PAUSED / COMPLETED).

"What hunts are live in my org right now?"

get_hunt

Returns one hunt's full configuration, including persona, target profile, ATS mapping, and current pipeline stats.

"Tell me everything about hunt X."

get_hunt_configuration

Returns the search criteria, sequences, and sender persona for a hunt — useful for auditing or cloning a hunt's setup.

"How is the EU sales hunt configured?"

get_organization_metrics

Aggregated funnel for the whole organization: hunts in each lifecycle status, with cross-hunt counts.

"Give me a quick read on my whole organization's pipeline."

get_hunt_metrics_timeseries

Time-series metrics for a hunt (or whole org) over a date range — candidates sourced, connections sent/accepted, messages sent/received, etc.

"Plot connections accepted over the last 30 days for hunt X."

get_hunt_metrics_distribution

Distribution metrics — pipeline status, score, years of experience, sentiment, tags — for a hunt or the whole org.

"What's the funnel breakdown on hunt X?"

list_candidates

Paginated list of candidates in a hunt or across the whole organization, filterable by connection or pipeline status. Returns LinkedIn URLs, names, current company, and pipeline state.

"Show me 50 candidates that accepted but didn't reply on hunt X."

get_candidate

Returns a candidate's full profile, including LinkedIn data, scoring rationale, and pipeline state.

"Tell me more about candidate Y."

get_candidate_messages

All inbound and outbound messages exchanged with a candidate, in order.

"What did I last say to candidate Y, and what did they reply?"

list_candidate_notes

Notes left on a candidate (yours and your teammates').

"What notes do we have on candidate Y?"


Troubleshooting guide


Rate limits


Rate limits depend on your Umamy plan and the AI tool you're using. Default limits average around 100 requests per minute across all tools and are subject to change. If you're consistently hitting them, reach out to support.


MCP tools not working


If your AI agent reports it can't access Umamy or use the MCP tools, try re-authenticating:


  1. Disconnect the Umamy connector in your AI tool.
  2. Reconnect and complete the OAuth flow again.
  3. Re-test with a simple prompt like "Which Umamy organizations am I in?"


Claude shows "No tools available"


If Umamy is connected in Claude but shows No tools available, reconnect the connector to reset the session:


  1. Go to Claude connector settings in your browser. You must do this on claude.ai even if you use the desktop app.
  2. Select Umamy.
  3. Click the three-dot menu in the top-right and choose Disconnect.
  4. Without refreshing the page, choose Connect again and complete authentication.


If you're on a Claude Team or Enterprise plan, you may need a workspace admin to disconnect and reconnect Umamy for you.


"Unauthorized" or "no organization found" after sign-in


If you see this after the OAuth flow completes, you may have signed in with a different email than the one your Umamy account uses, or you no longer belong to any organization.


To check which email your Umamy account uses, open Umamy and look at your account in the bottom-left corner of the sidebar. Reconnect MCP with that exact email.


MCP can't find any of my hunts or candidates


If your AI tool returns no results when you know there's data, MCP may be connected to the wrong Umamy account or you might be querying the wrong organization.


Ask your AI tool: "Which Umamy organizations am I in?" — it'll call list_organizations and return the list. Then:


  • Right account, wrong organization: pass the correct organization_id in the next prompt (e.g. "list candidates in organization <id>").
  • Wrong account entirely: disconnect and reconnect the connector with the correct Umamy login.


Signed into the wrong account in Claude


If you connected Claude to Umamy while signed into the wrong Umamy account:


  1. Go to claude.ai/customize/connectors.
  2. Find and disconnect the Umamy connector.
  3. Reconnect using the correct Umamy account.


General FAQ


Do I have to use the same email address for my AI tool and Umamy?


No — you can use different accounts for your AI tool and Umamy. During the OAuth flow, you authenticate the Umamy account you want your AI tool to act as.


Why can't my AI tool see a specific hunt or candidate?


Umamy MCP enforces the same access rules as the web app: you only see hunts in organizations you're a member of, and candidates inside those hunts. If a hunt is in another organization you don't belong to, it won't show up.


I just upgraded my plan — when will I get access to extra tools?


Upgrades take effect immediately. Your next MCP query will use the new plan's tools and rate limits.


Do I need a client ID or client secret?


No. Umamy MCP uses browser-based OAuth with Dynamic Client Registration (DCR), so credentials are handled automatically. If a third-party platform shows client ID and client secret fields, leave them blank — the platform will register with Umamy automatically.


Can I connect Umamy MCP to my own internal AI tool?


Yes — any tool implementing the MCP client specification with Streamable HTTP transport can connect. Your tool needs to handle the OAuth 2.0 browser authentication flow so each user can sign in to their Umamy account. See the customer API instead if you need a non-interactive service-account flow.


If you're building a custom integration and need help, reach out to support@umamy.io.

Updated on: 05/05/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!