# Connect an agent

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

Connect an MCP client to Recoup with OAuth and account-authorized tools.

Use this URL in your agent's remote MCP settings:

```text
https://api.recoupable.dev/mcp
```

Select **OAuth**. Recoup supports [published client metadata (CIMD)](https://recoupable.dev/docs/mcp-cimd) and **automatic registration** (also called Dynamic Client Registration or DCR). Sign in to your existing Recoup account and allow the requested access. No API key or client secret needs to be copied.

## What your agent can do

Request **`mcp:tools`** for the full catalog: a scope-dependent catalog covering artists and socials, catalogs, chats, scheduled tasks, research/search, Spotify, YouTube revenue, image/audio/video operations, files, Context, Sites, email and support.

The consent screen explains that this permission includes reading, creating, editing and deleting data, sending messages, publishing content, and using paid generation tools. It covers personal and organization workspaces your account can access. Resource ownership is checked on each call. Private conversations and scheduled tasks remain account-bound.

| Permission | Access |
| --- | --- |
| `mcp:tools` | Full business-tool catalog across accessible workspaces |
| `mcp:read` | Original personal-only `list_artists`, `get_artist_socials`, `get_chats` |
| `mcp:write` | Original personal-only `create_new_artist`, `update_account_info` |

Existing limited grants do **not** expand automatically. Reconnect with `mcp:tools`, review the broader permission, and refresh your client's tool catalog. Clients requesting the `mcp:read` + `mcp:write` pair keep the five-tool experience.

OAuth never exposes `get_api_key`: it does not return bearer credentials to the model. Composio integrations and sandbox execution are separate from the registered Recoup MCP catalog.

Email uses the same recipient restrictions as the API and checks any referenced conversation's owner. Review recipients and content before sending. `create_knowledge_base` and `generate_txt_file` publish to permanent public Arweave storage: use only content explicitly approved for that destination, never confidential material. Video generation returns an account-bound `id`; pass that entire value as `video_id` to the retrieval tools. Older raw provider video IDs cannot be used with OAuth. Task-run status requires verifiable caller ownership and returns status fields, not raw provider payloads or logs.

The platform verification results below describe the original five-tool catalog unless explicitly stated otherwise. They do not establish full-catalog production verification.

New connections stay authorized until you disconnect them, including when inactive. Five-minute access tokens renew through rotating refresh tokens. Disconnect an agent from [Connected agents](https://app.recoupable.dev/oauth/connections) to revoke its access and refresh tokens immediately.

Connections approved under the previous 30-day policy keep their original expiration. Reconnect once to approve access until disconnected.

## Claude

1. Open **Customize → Connectors → Add custom connector**.
2. Name it **Recoup** and enter the MCP URL above.
3. Choose **Sign in now**. **Register automatically** uses DCR; **published identity** uses CIMD. The production client tests below used DCR.
4. Connect, sign in to Recoup, and select **Allow access**.
5. In a new chat, ask Claude to list your Recoup artists. Review individual tool-use approvals when prompted.

Claude web was tested against production on October 7, 2026: connection, five-tool discovery, artist read, temporary artist creation/update/readback, artist socials, and another read after access-token expiry passed. The temporary artist was removed afterward.

Claude Desktop 2.26454.0 was also tested on October 7, 2026 using the same authorized connector: tool discovery, artist listing, temporary artist creation/update/readback passed. The test artist was removed afterward. Separate disconnect/reconnect checks are still pending. Local stdio configuration is a different transport. See [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## ChatGPT

In the interface tested on October 7, 2026:

1. Open **Plugins → Add → Add custom MCP server**.
2. Enter **Recoup**, the MCP URL, and **OAuth**.
3. Under advanced OAuth settings, confirm **Dynamic Client Registration (DCR)** and request `mcp:tools` for full access.
4. Create the plugin, connect it, and complete Recoup consent.
5. Start a chat with Recoup enabled and request an artist list.

ChatGPT web was tested against production on October 7, 2026: OAuth login, artist listing, and temporary artist creation/update/readback passed. The temporary artist was removed afterward. Refresh and disconnect/reconnect checks are pending. Workspace policy and account access may limit custom integrations. UI labels can differ; see [OpenAI's MCP setup documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

## Codex

```bash
codex mcp add recoup --url https://api.recoupable.dev/mcp
codex mcp login recoup --scopes mcp:tools
```

Complete the browser sign-in and consent, then ask Codex to list your Recoup artists. Codex CLI 0.161.0 passed production OAuth login and an actual `list_artists` call on October 7, 2026. Version 0.145.0 failed issuer-response validation; upgrade if using that version. Writes, refresh, and disconnect/reconnect remain unverified in Codex. Desktop and IDE surfaces must be verified separately. See [Codex MCP configuration](https://developers.openai.com/codex/mcp).

## Cursor

Add a remote server to your project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "recoup": {
      "url": "https://api.recoupable.dev/mcp"
    }
  }
}
```

Open Cursor's MCP settings and authenticate. Cursor Desktop passed production OAuth connection, five-tool discovery, and an actual `list_artists` call on October 7, 2026. Writes, refresh, disconnect/reconnect, and Cursor web/agent journeys remain unverified. See [Cursor's MCP guide](https://cursor.com/docs/mcp) for the current setup and workspace restrictions.

## Other agents and callbacks

Use a remote Streamable HTTP MCP client supporting OAuth discovery, authorization code flow with PKCE S256, and DCR. Recoup publishes:

- Resource metadata: `https://api.recoupable.dev/.well-known/oauth-protected-resource/mcp`
- Authorization-server metadata: `https://api.recoupable.dev/.well-known/oauth-authorization-server/api/oauth`
- Resource: `https://api.recoupable.dev/mcp`

Register the exact callback used by your client. Registration binds callbacks to that client; there is no shared wildcard callback list. Hosted callbacks use HTTPS. Native clients use validated loopback callbacks. Do not substitute `localhost` for `127.0.0.1` or edit a callback after registration.

A generic MCP SDK client has passed production reads, writes, refresh rotation, and revocation. That does not prove every agent surface. CIMD uses the same consent and permissions; see [CIMD requirements and verification status](https://recoupable.dev/docs/mcp-cimd). Full-tool consent includes accessible organization workspaces; the original limited grants remain personal-only.

### Additional client setup paths

The following paths were reviewed in official client documentation on October 7, 2026. **They have not been tested end to end against Recoup.** Use automatic registration and request `mcp:tools` for full access, or `mcp:read` / `mcp:write` for the limited personal tools. The client registers its callback; you do not need a Recoup platform-specific callback allowlist.

| Client | Setup and callback guidance |
| --- | --- |
| [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors) | Add a custom remote connector with OAuth and DCR. Use per-user authentication. Documented callbacks are `https://www.perplexity.ai/rest/connections/oauth_callback` and, for enterprise, `https://enterprise.perplexity.ai/rest/connections/oauth_callback`. |
| [Claude Code](https://code.claude.com/docs/en/mcp) | Add Recoup as an HTTP server and authenticate through `/mcp` inside Claude Code. Automatic registration uses a localhost callback; `--callback-port` can fix its port when required. |
| [VS Code](https://code.visualstudio.com/api/extension-guides/ai/mcp#authorization) | Add an HTTP server in `.vscode/mcp.json`. OAuth supports DCR; documented callbacks include `http://127.0.0.1:33418` and `https://vscode.dev/redirect`. Preserve the callback supplied by your VS Code surface. |
| [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) | Configure the MCP URL as `httpUrl` and authenticate with `/mcp auth recoup` inside the Gemini CLI chat. DCR uses `http://localhost:<random-port>/oauth/callback` unless configured otherwise. |
| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Add a remote MCP server and run `opencode mcp auth recoup`. OAuth supports automatic registration. Let the client supply its callback. |
| [Kiro](https://kiro.dev/docs/mcp/configuration/) | Add the remote MCP URL and use DCR. Set `oauth.oauthScopes` to Recoup's scopes; the default identity scopes do not grant Recoup tool access. Use the client's loopback callback. |
| [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) | Create an MCP OAuth credential with **Use Dynamic Client Registration** enabled. Use the exact callback shown by your n8n instance. |
| [Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Add an MCP tool using Streamable HTTP and OAuth dynamic discovery/registration. If setup asks for a callback, use the exact URL shown by Copilot Studio. |

Documented compatibility is a setup starting point. A successful connection still needs an actual tool call before it can be considered verified. Refresh and disconnect/reconnect should be checked before relying on unattended access.

## Disconnect

Open [Connected agents](https://app.recoupable.dev/oauth/connections) and disconnect the selected agent. Future requests and refreshes stop; already completed changes remain. Other connections are independent. Reconnect from the agent when you want to grant access again.

## Troubleshooting

| Symptom | What to do |
| --- | --- |
| Custom connector option missing | Check your client's plan and workspace-admin permissions. |
| Published identity / CIMD unavailable or fails | Check the [metadata requirements](https://recoupable.dev/docs/mcp-cimd), or choose automatic registration / DCR if your client offers it. |
| Connection request expired | Restart Connect from the client; do not reuse an old consent URL. |
| Wrong Recoup account | Use Switch before approving. |
| Still seeing only five tools | Reconnect requesting `mcp:tools`, approve full access, then refresh the client tool catalog. |
| Connected but no tool access | Check selected scopes, individual tool approvals, and whether the grant expired or was revoked. |
| Organization artist missing | Reconnect with `mcp:tools` and verify your organization membership. |
| `401` after disconnect | Expected: reconnect and approve a new grant. |
| `429` | Respect `Retry-After`; avoid repeated registration attempts. |
| `503` | Retry later; do not weaken authentication or callback checks. |
| Write timed out | Read back the target before retrying. Artist creation is not guaranteed idempotent; an automatic retry may create a duplicate. |

For clients without OAuth, [API-key authentication](https://recoupable.dev/docs/mcp) remains available. Keep keys out of model prompts and shared configuration. A stdio-only client needs a separately maintained adapter; the remote URL is not itself a stdio command.

For help, contact [agent@recoupable.dev](mailto:agent@recoupable.dev). Include the client name, time, and error text; never include tokens, passwords, or API keys.

Full OAuth MCP calls currently share account-level limits of 120 calls per minute
and 30 calls per tool per minute across connected clients. See the
[pinned rate-limit implementation](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/checkFullOAuthRateLimit.ts).
The `compact_chats` MCP tool accepts up to 50 chats per call under the
[pinned MCP guard](https://github.com/recoupable/api/blob/c25715ea1b5e31ac31d0079955b90dc1ce2f1631/lib/mcp/oauth/prepareFullOAuthTool.ts);
this is an MCP limit, not a claimed REST request limit.