# MCP server

Source: https://docs.recoupable.dev/mcp-server

Connect an agent to Recoup through OAuth and discover its authorized tools.

Connect your host to `https://api.recoupable.dev/mcp` using OAuth. Sign in to your real Recoup account and approve the requested scope. Follow the [OAuth setup guide](https://docs.recoupable.dev/mcp-oauth).

Use `tools/list` after connection and after changing consent. The catalog depends on the grant, credential type and deployed server. A fixed count is not a compatibility contract. For example, discover `list_artists` and call it with its returned schema to verify access. An empty roster is a valid result.

`mcp:tools` grants the business catalog, including writes and paid generation. Narrow grants remain restricted until broader consent is approved. Account membership determines accessible personal and organization data; OAuth consent does not create organization access.

Sandbox command tools previously shown on this page are absent from the current registry. Do not call `prompt_sandbox`, `run_sandbox_command`, or infer that every REST endpoint is exposed as MCP. Use documented [REST sandbox operations](https://docs.recoupable.dev/api-reference/sandboxes/create) with a separate authorized credential when required.

For an API-key MCP connection, configure `Authorization: Bearer YOUR_RECOUP_API_KEY` in the client's secret settings. The `x-api-key` header is for [REST requests](https://docs.recoupable.dev/authentication). Store credentials in the client's secret facility or environment. Never paste them into global instructions or extract host-managed OAuth tokens for REST.

## Public generated files

`generate_txt_file` and `create_knowledge_base` store content in public Supabase
Storage. Anyone with a returned URL can read it without authentication. Use
these tools only for content approved for public access, not confidential files.

For TXT results, prefer `txtUrl` and `metadataUrl`. The deprecated `arweaveUrl`
and `metadataArweave` fields remain aliases of those HTTPS URLs, not transaction
IDs. Metadata is best-effort, so `metadataUrl` and its alias can be null.
Knowledge entries keep their existing `url`, `name` and `type` fields.

Generated and edited image results retain `imageUrl`; it can be null if storage
fails. A successful tool envelope does not by itself establish a stored image.
Existing Arweave links remain readable. These changes do not migrate private
Files or [release-pack source audio](https://docs.recoupable.dev/release-packs).

## Context results

The [Context reference](https://docs.recoupable.dev/api-reference/context/operate) pairs each supported action
with its success status, response model and synthetic request/result examples.
Use the status declared for that action: `ingest` returns 202, while the specific
catalog, artist, release and text ingestion actions return 200. A 202 verification
receipt means queued after existing readiness checks, not completed work.
HTTP/standard MCP `read` may include a metadata-only `material_evidence` receipt;
delegated OAuth omits it. The examples do not verify hosted access or enable collection.

## Plan a catalog lookup

A catalog manager with an existing catalog Context request can plan a lookup for
its current expanded recording members. Standard MCP uses `context` with
`action: plan_catalog_members`; delegated OAuth uses `plan_music_catalog_research`
with the same input fields and no `action`. Discover the tool in the connected
client before use; this source mapping does not prove hosted availability.

Choose `recording_candidates`, `recording_work_candidates` or `platform_metadata`.
These plan possible recording matches, linked works or platform track information.
The response preserves the existing module values and node IDs, returns each node
blocked and has `collectionPermitted: false`. It does not fetch data, verify rights,
start collection or grant spending permission. The [Context reference](https://docs.recoupable.dev/api-reference/context/operate)
lists all accepted compatibility values, required IDs, page cursors and the complete response.

## Continue a catalog case

The source contract adds `save_catalog_case`, `read_catalog_case` and
`list_catalog_cases` to standard MCP; delegated OAuth excludes them. Discover the
tools in the connected host before using them. They also use the `context` tool
with the corresponding `action`. The catalog-case database and API release must
be deployed before this source contract is available.

A case keeps versioned sources, assessments, findings, proposed actions, attempts
and outcomes for the authorized workspace. No artist or ingestion request is
required. The stored snapshot is `customer_assertion` evidence and always returns
`external_actions: unsupported`: saving a record does not submit a registration,
send a claim, confirm a provider decision or verify a bank receipt.

For a new case, save with `expected_revision: 0` and `snapshot.revision: 0`.
For subsequent saves, use the current revision. Supply a unique idempotency key
for each new save. After an uncertain response, retry the unchanged payload with
the same key and expected revision.
Reads can withhold withdrawn evidence and its dependent records; explicitly
reassemble a partial snapshot before another save. The [Context reference](https://docs.recoupable.dev/api-reference/context/operate)
defines the complete bounded schema, historical-source rules, revision conflicts,
response fields and list pagination.

## Check an application proposal

The pending standard MCP tool `validate_application_registration` checks an
authorized workspace's proposed name, environment, exact origins and return URLs.
It returns `persisted: false` and `origins_verified: false`; it does not register
an application, prove domain ownership or issue application credentials.
Delegated OAuth excludes this tool, including grants with `mcp:tools`. Discover
it in a standard connection before use. See the [proposal preflight reference](https://docs.recoupable.dev/api-reference/applications/validate-registration)
for inputs, normal authentication effects and the limits of a successful result.

## Release Packs

When deployed and exposed by the current grant, the pack catalog includes
`prepare_release_pack`, `get_release_pack`, `estimate_release_pack`,
`generate_release_pack`, `retry_release_pack`, `upload_release_pack_asset` and
`export_release_pack`. These use the same account ownership, brief revisions,
complete quotes and budget limits as REST. No existing artist or GitHub workspace
is required. Use returned schemas and identifiers; preparation does not authorize
paid generation. See [Release Packs](https://docs.recoupable.dev/release-packs) for first use and upload limits.