> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Acquisition tools with MCP

> Connect an agent to paid Plyne acquisition tools with OAuth or an API key. Discover tool schemas, choose source chains and recover long-running requests safely.

Plyne acquisition MCP exposes the same tools and input/output schemas as the acquisition API. Use this connection when your agent needs to fetch new external data, rather than read results already saved in your workspace.

## Connect

Use `https://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 MCP `tools/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](https://docs.plyne.ai/tools/search-jobs.md).

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 to `plan_tool` without an idempotency key:

```json theme={null}
{
  "name": "plan_tool",
  "arguments": {
    "tool": "job_search",
    "input": {"keywords": ["engineer"], "limit": 10}
  }
}
```

Inspect `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

Use `list_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](https://docs.plyne.ai/tools/helpers.md) for API/MCP examples and the supported catalogs.

## Keep request identity

Use a new `idempotency_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.

## Use the shared reference

Every tool page documents API and MCP usage together. Parameters, provider options and output schemas come from the executable registry. [Tool execution](https://docs.plyne.ai/tools/overview.md) explains chain selection, pagination, statuses and error recovery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.