Connect
Usehttps://api.plyne.ai/mcp as a Streamable HTTP MCP server. Sign in through OAuth and authorize your workspace, or configure Authorization: Bearer $PLYNE_API_KEY with a valid workspace key in your MCP client. OAuth discovery is available at https://api.plyne.ai/.well-known/oauth-protected-resource/mcp.
The same /mcp connection includes saved workspace data and acquisition tools. Existing /mcp/tools connections remain supported for acquisition; new connections should use /mcp. OAuth tokens must include the endpoint being called in their audience, so moving an existing /mcp/tools OAuth connection to /mcp requires authorization for /mcp. Any valid workspace API key works on either endpoint without additional product-specific scopes.
Discover and call tools
The standard MCPtools/list response includes each tool’s description, input schema, output schema, tool-specific billing guidance, discovery groups and a call example. Tool names match API IDs, such as job_search.
Read the plyne://tools/{id} resource through resources/read for the complete documentation, examples and schemas without an acquisition call. resources/list lists these tool references and plyne://tools/catalog. Read that catalog resource to explore the same signal and capability groups as the portal and docs. Each collection contains tool IDs; a tool can appear under more than one signal. Grouping does not turn raw data into a verified buying signal.
Tool groups are distinct from list_catalogs, which lists accepted parameter-value catalogs. Shared authentication, source-chain and retry rules are supplied in the MCP server instructions; complete per-tool contracts remain available in the reference resources.
Use a tool reference’s MCP example as the tools/call parameters. The input is the same as the API body with an additional idempotency_key. For a complete example, see Search jobs.
A tool can spend workspace credits. Inspect the billing policy and selected result limit before requesting acquisition. Call the free plan_tool helper before a new acquisition to validate the proposed input and inspect current source eligibility and the maximum credit reservation. Planning does not fetch data or reserve credits.
Plan before acquisition
Read the selected tool reference first, then pass its proposed request body toplan_tool without an idempotency key:
providers and pricing. An eligible source is not a guarantee that matching data exists. If the plan succeeds and the user requested acquisition, call job_search with the same input plus a new idempotency_key. For record-priced tools, the reservation quote includes the requested limit.
Planning is also available through POST /v1/tools/{id}/plan; both interfaces use the same planning logic.
Free parameter helpers
Uselist_catalogs, search_catalog and get_field_options to discover exact accepted filter values before acquisition. These read-only helpers cost 0 Plyne credits and do not accept or require an idempotency key. See Free parameter helpers for API/MCP examples and the supported catalogs.
Keep request identity
Use a newidempotency_key for a new operation. Reuse the original arguments and key when retrieving that operation. For a pending result, call the same tool again with the same arguments and key; do not generate a new key for each progress check.
If the client loses the connection, retrieve the original request. A completed replay returns the saved result without another acquisition charge. A new key can start another paid job.