MCP server

Ploid's hosted MCP server uses Streamable HTTP and OAuth 2.1. The connection is scoped to the Ploid workspace you approve and uses that workspace's ACU balance.

Connect 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.

Connect 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.

Available tools

The three research tools can consume paid usage from your workspace's ACU balance. Status retrieval is read-only and does not start another investigation. Cancellation stops a run but does not refund work already done.

The earlier personalize_message, research_company, and run_agent tools were removed together with the Agent API. Reconnect or rebuild your MCP client to refresh its tool list.

Research a person

Call research_person with linkedin_url, or with name plus company_domain, the web domain of the person's company. A company URL is reduced to its domain. linkedin_url takes precedence when both are given. Any other input returns a tool error asking for one of these identifiers.

For example, these are arguments to research_person:

{
    "name": "Ada Lovelace",
    "company_domain": "analytical-engines.example"
}

The tool calls POST /v1/person, which has one deep mode. The first successful profile of a person costs a fixed 25 ACU; the same workspace can reread it free for 90 days. Not-found and uncertain-identity results are free.

Research checks identity links and reviews claims against retrieved pages. Search snippets are discovery leads, not supporting evidence. Results can include historical claims and limitations; reading a page today does not make its information current. When the evidence cannot establish one identity, the result has found: false and suggested clues instead of a same-name biography. Retry with a LinkedIn URL when one is known.

Find people and decision-makers

find_people takes a natural-language query and a count of up to 25. find_decision_makers takes a company, the product being sold, optional titles to prioritize, and a count of up to 20. Both create a People Set through POST /v1/sets. Each candidate is checked against criteria: derived from the query for find_people, or built from the company, product, and titles for find_decision_makers. Sets prices search at 1 ACU per 10 people; the pending and final results include its pricing object.

A completed result lists each verified person with name, title, company, location, LinkedIn URL when known, and the verification against the criteria.

Long research and results

Research tools return promptly with a run_id; this is an acknowledgement, not the finished research. Person runs have IDs like person-<id> and searches have IDs like set-<id>. For example, the tool's structuredContent can contain:

{
    "status": "queued",
    "run_id": "person-cmf1abc",
    "retry_after_seconds": 10,
    "next": {
        "tool": "get_research_status",
        "arguments": { "run_id": "person-cmf1abc" }
    }
}

Call get_research_status with that run_id no more often than every five seconds while the status is queued or running. A finished result has status: "completed": a person result includes found, the person record, and usage; a search result includes the verified people. A cancelled run returns status: "cancelled". A failed, expired, or unknown run returns a tool error that says the run has ended; stop polling on a terminal result or error. A person result that predates source review also ends the run, and the error asks you to start research_person again. A temporary error, such as a status-request timeout, a network failure, a rate limit, or a gateway error, returns a tool error saying the run continues; check the same run ID again later.

Keep the run ID to retrieve the result after reconnecting or restarting Claude. Every lookup is authorized against the connected workspace. Person run data is retained for seven days, after which retrieval returns an expiry error. Run IDs issued by the removed Agent tools can no longer be retrieved.

Each MCP-to-API HTTP request has a 20-second deadline. Research runs in a background job and may take minutes; disconnecting or a status-request timeout does not automatically cancel it. Execution deadlines still apply. The client also decides how long it will keep polling, so MCP does not guarantee unlimited runtime or automatic polling after a restart.

Cancel research

Only call cancel_research when the user asks to stop a run. It takes the same { "run_id": "..." } arguments as status retrieval. Cancelling a person run returns status: "cancelled". Cancelling a search returns status: "cancel_requested"; people it admitted before stopping are kept and billed. Call get_research_status for the final state.

For a local stdio server, rebuild and reconnect it in Claude after upgrading to load the new tool definitions. Hosted connections use the deployed server build.

Permissions

Hosted connections are granted agent:chat, people:enrich, people:search, and account:read. Connections approved before the Person and Sets tools were upgraded to the people permissions automatically, so they keep working without reconnecting.

A local server signed in with npx @ploid/mcp login uses the same key as the Ploid CLI and gets the CLI's default permissions: people:enrich, people:search, linkedin:read, account:read, and account:write. Keys created before people:search existed keep working for searches when they already had full access (people:enrich and agent:chat). A key from npx @ploid/mcp login 0.2.0 or earlier has only agent:chat and account:read; run the login command again to replace it.

Authentication and revocation

Ploid supports OAuth discovery, dynamic client registration, authorization code with S256 PKCE, one-hour access tokens, rotating refresh tokens, and revocation. Disconnect Ploid from your AI client's connector settings or revoke the generated MCP · ... key in Ploid workspace settings.

The implementation is open source at github.com/ploidcom/ploid-mcp.