Skip to content

docs: MCP tool catalog rewrite #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
recoupableorg wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: MCP tool catalog rewrite #170

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 130 additions & 47 deletions mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,161 @@
---
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot Apr 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

mcp.mdx exceeds the custom maximum file size limit (161 lines vs required under 100), reducing readability and maintainability per Rule 2.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At mcp.mdx, line 39:

<comment>`mcp.mdx` exceeds the custom maximum file size limit (161 lines vs required under 100), reducing readability and maintainability per Rule 2.</comment>

<file context>
@@ -1,78 +1,161 @@
+---
 
-**Response fields:**
+## Tool catalog
 
-| Field | Type | Description |
</file context>
Fix with Cubic

title: "MCP"
description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server."
title: "MCP Server"
description: "Connect any AI agent to Recoup via the Model Context Protocol — Claude, ChatGPT, Cursor, and 40+ Recoup tools natively."
---

The Recoup API exposes an [MCP](https://modelcontextprotocol.io/) server that AI agents can connect to for tool use. The server is available at:
Recoup exposes an [MCP](https://modelcontextprotocol.io/) server so any AI agent can use Recoup tools natively. Claude, ChatGPT, Cursor, Windsurf, and any MCP-compatible agent can research artists across Spotify and the open web, generate images and videos, manage catalogs, schedule tasks, and more — without writing API calls.

```
https://recoup-api.vercel.app/mcp
```

## Authentication
## Setup

All MCP tools require an API key. Pass it as a Bearer token in the `Authorization` header when connecting to the MCP server.
Pass your API key as a Bearer token when connecting:

You can get a key from the [API Keys page](https://chat.recoupable.com/keys).
```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

## Tools
const RECOUP_API_KEY = process.env.RECOUP_API_KEY;

### prompt_sandbox
const transport = new StreamableHTTPClientTransport(
new URL("https://recoup-api.vercel.app/mcp"),
{ requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } },
);

Send a prompt to OpenClaw running in a persistent per-account sandbox. The sandbox is reused across calls — if one is already running it picks up where you left off, otherwise a new one is created from the account's latest snapshot.
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
```

Returns raw `stdout` and `stderr` from the command. The sandbox stays alive after each prompt for follow-up interactions.
Get a key from the [API Keys page](https://chat.recoupable.com/keys) or use the [agent signup](/agents) for instant generation.

**Input schema:**
<Tip>
Privy JWTs are also accepted as Bearer tokens for browser-based agents that already authenticate users via Privy.
</Tip>

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | `string` | Yes | The prompt to send to OpenClaw in the sandbox. |
---

**Response fields:**
## Tool catalog

| Field | Type | Description |
|-------|------|-------------|
| `sandboxId` | `string` | The Vercel Sandbox ID. |
| `stdout` | `string` | Standard output from the command. |
| `stderr` | `string` | Standard error from the command. |
| `exitCode` | `number` | Process exit code (`0` = success). |
| `created` | `boolean` | `true` if a new sandbox was created, `false` if an existing one was reused. |
The server exposes 40+ tools organized by domain. Every tool returns structured JSON suitable for chaining into multi-step agent workflows.

**Example usage (TypeScript with MCP SDK):**
### Artists

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
| Tool | What it does |
|------|-------------|
| `create_new_artist` | Create a new artist account in the system. |
| `get_artist_socials` | Retrieve all socials (handle, avatar, profile URL, bio, follower count, following count) associated with an artist. |
| `update_artist_socials` | Update the social profiles linked to an artist. |
| `update_account_info` | Update an artist's `account_info` record. |

const transport = new StreamableHTTPClientTransport(
new URL("https://recoup-api.vercel.app/mcp"),
{ requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } },
);
### Catalog

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
| Tool | What it does |
|------|-------------|
| `select_catalogs` | Get catalogs for an account. |
| `select_catalog_songs` | Find songs in the catalog for playlists or music recommendation tasks. |
| `insert_catalog_songs` | Add songs to a catalog by ISRC in batch. |

### Chats

| Tool | What it does |
|------|-------------|
| `get_chats` | Get chat conversations for accounts. |
| `compact_chats` | Compact one or more chat conversations into concise summaries. |

### Content — images, video, audio

| Tool | What it does |
|------|-------------|
| `generate_image` | Generate an image from a text prompt. |
| `edit_image` | Edit existing images. |
| `search_google_images` | Search for existing images on Google Images. |
| `generate_sora_2_video` | Generate a video from a text prompt using OpenAI's Sora 2. |
| `retrieve_sora_2_video` | Retrieve the status and details of a video generation job. |
| `retrieve_sora_2_video_content` | Download the rendered video content for a completed job. |
| `transcribe_audio` | Transcribe audio (music, podcast, voice memo) using OpenAI Whisper. |
| `analyze_music` | Analyze music or answer music questions using Recoup's Audio Language Model. |

### Research

| Tool | What it does |
|------|-------------|
| `search_web` | Default web search tool — use first for any general information lookup. |
| `web_deep_research` | Multi-source deep web research with comprehensive analysis. |
| `artist_deep_research` | Comprehensive cross-platform research on a specific artist with a generated report. |
| `spotify_deep_research` | Deep research on an artist using a Spotify ID. |

### Spotify

| Tool | What it does |
|------|-------------|
| `get_spotify_search` | Search Spotify for artists, albums, tracks, or playlists by name. |
| `get_spotify_album` | Retrieve Spotify catalog information for a single album. |
| `get_spotify_artist_albums` | Retrieve Spotify catalog information about an artist's albums. |
| `get_spotify_artist_top_tracks` | Retrieve an artist's top tracks by country. |

### YouTube

| Tool | What it does |
|------|-------------|
| `youtube_login` | Check YouTube authentication status for an account. |
| `get_youtube_channels` | Get YouTube channel information for an account. |
| `get_youtube_channel_video_list` | Get a list of videos for a specific YouTube channel. |
| `get_youtube_revenue` | Get estimated revenue for a date range for a YouTube account. |
| `set_youtube_thumbnail` | Set a custom thumbnail for a YouTube video. |

### Tasks

Background work scheduled and managed through the Recoup task system.

| Tool | What it does |
|------|-------------|
| `get_tasks` | List existing tasks. |
| `create_task` | Create a new task. |
| `update_task` | Update an existing task. |
| `delete_task` | Delete a task. |
| `get_task_run_status` | Get the status of a task run by its run ID. |

### Pulses

| Tool | What it does |
|------|-------------|
| `get_pulses` | Get pulse statuses for accounts. |
| `update_pulse` | Update the pulse status for an account. |

### Sandbox

| Tool | What it does |
|------|-------------|
| `prompt_sandbox` | Create a per-account sandbox and run an OpenClaw prompt inside it. Returns the sandbox ID and a run ID for tracking progress. |

### Utilities

| Tool | What it does |
|------|-------------|
| `get_local_time` | Get the current local time/date. |
| `send_email` | Send an email via Resend. |
| `contact_team` | Send a message to the Recoup team. |
| `generate_txt_file` | Create a downloadable text file from provided contents. |
| `create_knowledge_base` | Save a plain-text knowledge base entry to permanent Arweave storage. |

---

## Calling a tool

Once connected, call any tool by name. Example — kick off an OpenClaw prompt in a sandbox:

```typescript
const result = await client.callTool({
name: "prompt_sandbox",
arguments: { prompt: "list all files in the orgs directory" },
});

console.log(result.content);
```

### run_sandbox_command

Create a sandbox and run a shell command or OpenClaw prompt in it. Unlike `prompt_sandbox`, this creates a **new sandbox each call** and runs the command asynchronously via a background task. Returns a sandbox ID and run ID to track progress.

See [`POST /api/sandboxes`](/api-reference/sandboxes/create) for the equivalent REST endpoint.

**Input schema:**
Each tool's input schema is published over the MCP protocol, so your agent gets typed parameter help automatically.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot Apr 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Documentation and Naming Conventions for Maintainable Code

Public API docs removed concrete response/error behavior details and replaced them with generic schema guidance, reducing clarity on error transitions required by the rule.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At mcp.mdx, line 157:

<comment>Public API docs removed concrete response/error behavior details and replaced them with generic schema guidance, reducing clarity on error transitions required by the rule.</comment>

<file context>
@@ -1,78 +1,161 @@
-See [`POST /api/sandboxes`](/api-reference/sandboxes/create) for the equivalent REST endpoint.
-
-**Input schema:**
+Each tool's input schema is published over the MCP protocol, so your agent gets typed parameter help automatically.
 
-| Parameter | Type | Required | Description |
</file context>
Fix with Cubic


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `command` | `string` | No | Shell command to run. Cannot be used with `prompt`. |
| `args` | `string[]` | No | Arguments for the command. |
| `cwd` | `string` | No | Working directory for the command. |
| `prompt` | `string` | No | OpenClaw prompt. Cannot be used with `command`. |
| `account_id` | `string` | No | Target a specific account (org API keys only). |
<Note>
**Org-scoped keys** can target any account in their organization by passing `account_id` on tools that accept it. Personal API keys can only operate on their own data.
</Note>