MCP server

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.

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

Context results

The Context reference 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 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 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 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 for first use and upload limits.