Ploid MCP

Give ChatGPT, Claude, and other MCP clients source-reviewed person research and verified lists of people and decision-makers.

Connect the hosted server

Use this Streamable HTTP endpoint:

https://api.ploid.com/mcp

The endpoint supports MCP 2026-07-28 discovery and requests alongside the older initialize flow and standalone SSE stream. Existing connections can continue using their negotiated protocol version.

The first tool call opens Ploid's OAuth login and consent page. Access is tied to the workspace you choose, tokens are scoped and expiring, and tool calls use that workspace's ACU balance.

ChatGPT

1. Open Settings → Security and login and enable Developer mode.

2. Open ChatGPT Plugins, select +, and create a connection.

3. Enter https://api.ploid.com/mcp as the MCP server URL.

4. Sign in to Ploid, choose a workspace, and approve access.

Claude

1. Open Customize → Connectors.

2. Select + → Add custom connector.

3. Enter Ploid and https://api.ploid.com/mcp.

4. Select Connect, then sign in to Ploid and approve access.

No client ID, client secret, or API key is required. The server supports OAuth 2.1 discovery, dynamic client registration, authorization code + S256 PKCE, refresh-token rotation, and revocation.

Related MCP server: FullEnrich MCP

Tools

search_people costs 1 ACU per completed search, including searches with no matches. Failed searches are not charged. The three research tools also consume paid usage. Status retrieval is read-only; cancellation stops a run and does not refund work already done.

Version 0.3.0 removed personalize_message, research_company, and run_agent, which depended on the retired Agent API, and removed the depth, goal, company, and website_url inputs of research_person.

Research a person

For a name such as "Rahul Garg", call search_people first. It accepts name with optional company, location, and title filters; limit defaults to 5 and must be 1 to 10. It returns basic indexed profiles, not verified research. Results are bounded and may omit matches. No matches does not mean the person does not exist.

Show the candidates and ask the user to choose, even if there is only one. Then call research_person with exactly one of person_id from the chosen result or an explicit HTTPS LinkedIn /in/ profile URL as linkedin_url; the schema's anyOf and the error text both say so. Name and company arguments are no longer accepted. Do not research every candidate to resolve an ambiguous name.

/v1/person has one deep mode. The first successful profile of a person costs a fixed 25 ACU in the connected workspace; the same workspace can reread it free for 90 days. Not-found and uncertain-identity results are free. An uncertain result returns found: false with suggested clues rather than a same-name biography.

Find people and decision-makers

find_people (count 1 to 25) and find_decision_makers (count 1 to 20) create a Ploid Set. Each candidate is checked against criteria: derived from the query for find_people, and built from the company, product, and optional titles for find_decision_makers. Sets prices search at 1 ACU per 10 people; the pending and final results include the Sets API's pricing object.

Input ranges are checked, not clamped

Tool schemas state each range in the field description instead of JSON-schema minimum, maximum, or maxLength, because some LLM clients clamp arguments to advertised bounds before the call reaches the server, turning an out-of-range request into a billable in-range one. src/bounds.ts checks the range on the server and returns an isError result naming it (for example limit: must be a whole number between 1 and 10 (got 11)) before any API request, so nothing is charged. The API repeats the check with a 422.

Long research and timeouts

Research tools return a run_id promptly. Person runs look like person-<id> and searches look like set-<id>; the prefix routes status and cancellation to the right API. A pending response is not a research answer. Call get_research_status with that ID no more often than every five seconds until it returns status: completed and the result. Keep the ID to resume from another MCP process or after restarting Claude. The API authorizes every lookup against the connected workspace. Run IDs from the removed Agent tools can no longer be retrieved.

Stop polling a failed or cancelled run. A pending response's 0 ACU is usage so far; a successful completion may still charge 25 ACU.

get_email and get_phone request the person at the standard level, so a profile researched at either level is reread for free and an unresearched person starts standard research (10 ACU on success) with the contact attached to the completed run; they never upgrade a standard profile to deep.

Each MCP-to-API HTTP request has a 20-second deadline, except get_email and get_phone on an already-researched person, which wait up to 90 seconds for the API's provider lookup. The investigation runs in the API's durable job, independently of these short calls. Disconnecting or a status-request timeout does not automatically cancel it. The API's execution deadline and result retention still apply; MCP itself does not guarantee unlimited runtime or that a client will poll forever.

Hosted HTTP retries reuse the same result or job without a second charge for the same authenticated connection, MCP session (when supplied), JSON-RPC ID, tool and arguments during the API's 24-hour idempotency window. If the initial acknowledgement is lost, retry those values. For an intentional new operation, use a new JSON-RPC ID or Idempotency-Key header; preserve that header across retries. Once a run_id is known, resume with get_research_status. Restarted stdio processes have separate namespaces.

Only call cancel_research on an explicit user request. Cancelling a search keeps, and bills, people it admitted before stopping.

After rebuilding a local stdio server, reconnect it in Claude to load the new tool definitions. A hosted server continues using its deployed build.

Run locally (stdio)

Node.js 20+ and pnpm are required.

pnpm install
pnpm test
pnpm build
node dist/cli.js login     # or: export PLOID_API_KEY=ploid_live_...
node dist/cli.js           # start the stdio server

Or with Docker:

docker build -t ploid-mcp .
docker run -i --rm -e PLOID_API_KEY=ploid_live_... ploid-mcp

PLOID_API_BASE_URL overrides the API (default https://api.ploid.com). The reusable Streamable HTTP entry point is handlePloidMcpRequest(request, { apiKey, baseUrl }) from src/server.ts. The hosted service authenticates the bearer token before calling it.

This repository is a mirror of the server in Ploid's private monorepo. Open issues and pull requests here; accepted changes are applied upstream and mirrored back. src/contracts.d.ts holds the Ploid API wire types the server uses, generated from the private package; it contains types only.

Security

• The MCP endpoint requires a bearer token before initialization or tool discovery.

• OAuth access is limited to agent:chat, people:enrich, people:search, and account:read. Connections authorized before 0.3.0 were upgraded to the people scopes on the server, so they keep working.

• ploid-mcp login writes the key the Ploid CLI also uses, so it receives the CLI's default scopes: people:enrich, people:search, linkedin:read, account:read, and account:write. Older full-access keys (people:enrich + agent:chat) can still build Sets. Keys from ploid-mcp login 0.2.0 or earlier (only agent:chat + account:read) must log in again.

• Authorization codes expire after five minutes and can be redeemed only once.

• PKCE uses S256; redirect URIs must exactly match the registered client.

• Access tokens expire after one hour; refresh tokens rotate on every use.

• Ploid stores only hashes of client secrets, authorization codes, access tokens, refresh tokens, and API keys.

• The MCP bearer token is audience-bound and is never passed through to Ploid's upstream API.

See LICENSE and SECURITY.md. Security reports: security@ploid.com.