MCP server

Hosted endpoint

Use https://api.ploid.com/mcp. No API key, OAuth client ID, or client secret needs to be copied into ChatGPT or Claude.

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

Open Settings → Security and login and enable Developer mode.
Open ChatGPT Plugins, select +, and create a connection.
Enter https://api.ploid.com/mcp as the MCP server URL.
Sign in to Ploid, choose a workspace, and approve access.

Connect Claude

Open Customize → Connectors.
Select + → Add custom connector.
Enter Ploid and https://api.ploid.com/mcp.
Select Connect, then sign in to Ploid and approve access.

Available tools

Tool	Purpose
`research_person`	Start sourced person research with standard or deep investigation
`find_people`	Find a sourced cohort from a natural-language query
`find_decision_makers`	Identify likely buyers and influencers at a company
`personalize_message`	Draft evidence-grounded outreach
`research_company`	Build a sourced company and buyer brief
`run_agent`	Run a broader natural-language Ploid Agent job
`get_research_status`	Retrieve a run's status or completed result using its `run_id`
`cancel_research`	Explicitly stop a run; requires the `agent:cancel` permission

The six 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 consumed.

Research a person

Call research_person with at least one of name, linkedin_url, or website_url. A known LinkedIn profile or personal website can be supplied without a name. Company and goal provide additional context.

Input	Description
`name`	The person's name
`company`	A company clue to help distinguish matching people
`linkedin_url`	A known LinkedIn profile URL
`website_url`	A known personal website URL
`goal`	What you want to learn about the person
`depth`	`standard` by default; use `deep` for a thorough investigation

For example, these are arguments to research_person:

{
    "name": "Ada Lovelace",
    "goal": "Research her professional history and distinguish dated claims from current information.",
    "depth": "deep"
}

Research checks identity links and reviews claims against retrieved pages. Search snippets are discovery leads, not supporting evidence. A company clue is not itself proof of employment. Results can include historical claims, unverified topics, and limitations; reading a page today does not make its information current. If the evidence cannot establish an identity, do not treat a same-name biography as a confirmed match. Providing a known profile or website can help a subsequent request.

Long research and results

Research tools use the Agent API. Work queued by the API returns promptly with a run_id; this is an acknowledgement, not the finished research. For example, the tool's structuredContent can contain:

{
    "status": "queued",
    "run_id": "run_123",
    "retry_after_seconds": 5,
    "next": {
        "tool": "get_research_status",
        "arguments": { "run_id": "run_123" }
    },
    "usage": {}
}

Call get_research_status with { "run_id": "run_123" } no more often than every five seconds while the status is queued or running. A finished result has status: "completed" and includes the research output, any structured results or artifacts, and usage. A cancelled run returns status: "cancelled"; failed or expired runs return a tool error. Stop polling on a terminal result or error. A temporary status-request timeout can be retried with the same run ID.

Keep the run ID to retrieve the result after reconnecting or restarting Claude. Every lookup is authorized against the connected workspace. Run data is retained for seven days, after which retrieval returns an expiry error.

Each MCP-to-API HTTP request has a 20-second deadline. Queued research runs in a background job and may take minutes; disconnecting or a status-request timeout does not automatically cancel it. Execution deadlines and research budgets 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": "run_123" } arguments as status retrieval.

Cancellation requires agent:cancel. Hosted OAuth connections currently allow research and status retrieval but do not grant this permission; cancellation requires an API key with agent:cancel. A permission error means cancellation was not authorized, not that the run stopped. Work already consumed may still be charged.

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.

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.