From edc3932924129314caff24923e8dce39db8ecba7 Mon Sep 17 00:00:00 2001
From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com>
Date: Mon, 27 Apr 2026 13:44:32 -0400
Subject: [PATCH] docs: MCP tool catalog rewrite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Brings mcp.mdx in line with what's actually registered in the
production MCP server (api/lib/mcp/tools/). The previous page
documented 2 tools; the actual server registers 43 across 11
domains.
Replaces the previous 2-tool description with a real tool catalog
grouped by activity:
- Artists (4 tools) - Spotify (4)
- Catalog (3) - YouTube (5)
- Chats (2) - Tasks (5)
- Content — image, video, - Pulses (2)
audio (8) - Sandbox (1)
- Research (4) - Utilities (3)
Tool names and descriptions extracted directly from the
register*Tool.ts source files for accuracy.
Also fixes:
- Removes the fictional `run_sandbox_command` tool (never existed
in the registered tool set).
- Drops the "Beta" framing — 43 working tools is just under-
marketed production, not beta.
- Trims the overpromise in the opening line to match the actual
capability surface.
Made-with: Cursor
---
mcp.mdx | 177 +++++++++++++++++++++++++++++++++++++++++---------------
1 file changed, 130 insertions(+), 47 deletions(-)
diff --git a/mcp.mdx b/mcp.mdx
index 05709d87..ec24e52b 100644
--- a/mcp.mdx
+++ b/mcp.mdx
@@ -1,78 +1,161 @@
---
-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:**
+
+Privy JWTs are also accepted as Bearer tokens for browser-based agents that already authenticate users via Privy.
+
-| 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.
-| 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). |
+
+**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.
+