From e0836700dbf2a963c3bc443c6d69d9c90f5bca83 Mon Sep 17 00:00:00 2001 From: Recoup Agent Date: Tue, 24 Mar 2026 21:14:49 +0000 Subject: [PATCH 1/4] docs: expand MCP page with full tool list and docs search MCP explanation --- mcp.mdx | 205 ++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 163 insertions(+), 42 deletions(-) diff --git a/mcp.mdx b/mcp.mdx index 05709d8..819049b 100644 --- a/mcp.mdx +++ b/mcp.mdx @@ -1,45 +1,39 @@ --- -title: "MCP" -description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server." +title: "MCP Servers" +description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP)." --- -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 two MCP servers: one for **searching these docs**, and one for **calling Recoup tools** from your AI agent. -``` -https://recoup-api.vercel.app/mcp -``` +--- -## Authentication +## 1. Docs Search MCP -All MCP tools require an API key. Pass it as a Bearer token in the `Authorization` header when connecting to the MCP server. +Every page in these docs includes an **MCP** button in the contextual menu (top-right of each page). Clicking it gives you a ready-to-use config snippet to add the Recoup docs as an MCP source in Claude, Cursor, VS Code, or any MCP-compatible client. -You can get a key from the [API Keys page](https://chat.recoupable.com/keys). +This server is powered by Mintlify and lets AI assistants search and read the Recoup API documentation directly — useful for building integrations or answering questions about the API. -## Tools +--- -### prompt_sandbox +## 2. Recoup API MCP Server -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. +The Recoup API exposes an MCP server that AI agents can connect to for tool use. The server is available at: -Returns raw `stdout` and `stderr` from the command. The sandbox stays alive after each prompt for follow-up interactions. +``` +https://recoup-api.vercel.app/mcp +``` -**Input schema:** +### Authentication -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `prompt` | `string` | Yes | The prompt to send to OpenClaw in the sandbox. | +All tools require an API key passed as a Bearer token: -**Response fields:** +``` +Authorization: Bearer +``` -| 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. | +Get a key from the [API Keys page](https://chat.recoupable.com/keys). -**Example usage (TypeScript with MCP SDK):** +### Connecting ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; @@ -52,27 +46,154 @@ const transport = new StreamableHTTPClientTransport( const client = new Client({ name: "my-agent", version: "1.0.0" }); await client.connect(transport); +``` + +--- + +### Tool Reference + +#### Artists + +| Tool | Description | +|------|-------------| +| `create_new_artist` | Create a new artist account. | +| `get_artist_socials` | Get all social profiles linked to an artist. | +| `update_artist_socials` | Set social profile URLs for an artist (platform auto-detected). | +| `artist_deep_research` | Run comprehensive research on an artist across platforms. | +| `update_account_info` | Update an artist's profile info (name, image, instructions, knowledge base). | + +#### Chats + +| Tool | Description | +|------|-------------| +| `get_chats` | List chat conversations, optionally filtered by account or artist. | +| `compact_chats` | Summarize one or more chat conversations into concise notes. | + +#### Tasks + +| Tool | Description | +|------|-------------| +| `get_tasks` | List scheduled tasks, optionally filtered by account, artist, or enabled status. | +| `create_task` | Create a new scheduled task. | +| `update_task` | Update an existing task. | +| `delete_task` | Delete a task by ID. | +| `get_task_run_status` | Get the status of a Trigger.dev background task run. | + +#### Pulses + +| Tool | Description | +|------|-------------| +| `get_pulses` | Get pulse statuses for accounts. | +| `update_pulse` | Enable or disable the pulse for the authenticated account. | + +#### Catalogs & Songs + +| Tool | Description | +|------|-------------| +| `select_catalogs` | List catalogs for an account. Call this first before recommending songs. | +| `select_catalog_songs` | Find songs from a catalog matching given criteria. | +| `insert_catalog_songs` | Add songs to a catalog by ISRC in batch. | + +#### Spotify + +| Tool | Description | +|------|-------------| +| `get_spotify_search` | Search Spotify for artists, albums, tracks, playlists, shows, or episodes. | +| `get_spotify_artist_albums` | Get an artist's albums from Spotify. | +| `get_spotify_artist_top_tracks` | Get an artist's top tracks by market. | +| `get_spotify_album` | Get details for a single Spotify album. | +| `spotify_deep_research` | Deep-research an artist using their Spotify ID. | + +#### YouTube + +| Tool | Description | +|------|-------------| +| `youtube_login` | Check YouTube authentication status for an artist. | +| `get_youtube_channels` | Get YouTube channel info for an artist. | +| `get_youtube_channel_video_list` | List videos from a YouTube channel's uploads playlist. | +| `get_youtube_revenue` | Get estimated YouTube revenue data for a date range. | +| `set_youtube_thumbnail` | Set a custom thumbnail for a YouTube video. | + +#### Search & Research + +| Tool | Description | +|------|-------------| +| `search_web` | Search the web for real-time information via Perplexity. | +| `search_google_images` | Search Google Images for photos or visual content. | +| `web_deep_research` | Deep web research using Perplexity's `sonar-deep-research` model. | + +#### Images +| Tool | Description | +|------|-------------| +| `generate_image` | Generate an image from a text prompt. | +| `edit_image` | Edit an existing image using a text prompt. | + +#### Video + +| Tool | Description | +|------|-------------| +| `generate_sora_2_video` | Generate a video from a text prompt using OpenAI Sora 2. | +| `retrieve_sora_2_video` | Get the status and details of a video generation job. | +| `retrieve_sora_2_video_content` | Download the rendered video content. | + +#### Audio + +| Tool | Description | +|------|-------------| +| `transcribe_audio` | Transcribe an audio file using OpenAI Whisper (MP3, WAV, M4A, WebM). | +| `analyze_music` | Analyze a track using the Music Flamingo model (mood tags, metadata, sync briefs, etc.). | + +#### Files & Knowledge + +| Tool | Description | +|------|-------------| +| `create_knowledge_base` | Save a plain-text knowledge base entry to an artist's permanent storage. | +| `generate_txt_file` | Create a downloadable TXT file stored on Arweave. | + +#### Communication + +| Tool | Description | +|------|-------------| +| `send_email` | Send an email via the Resend API. | +| `contact_team` | Send a support message to the Recoup team. | + +#### Segments + +| Tool | Description | +|------|-------------| +| `create_segments` | Analyze fan data and generate audience segments for an artist. | + +#### Sandboxes + +| Tool | Description | +|------|-------------| +| `prompt_sandbox` | Run an OpenClaw prompt inside a persistent per-account sandbox. Returns `stdout`, `stderr`, `exitCode`, and the sandbox ID. | + +#### Utilities + +| Tool | Description | +|------|-------------| +| `get_local_time` | Get the current date and time for a given IANA timezone. | + +--- + +### Example: calling a tool + +```typescript const result = await client.callTool({ - name: "prompt_sandbox", - arguments: { prompt: "list all files in the orgs directory" }, + name: "search_web", + arguments: { query: "top hip hop releases this week", max_results: 5 }, }); 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:** +```typescript +const result = await client.callTool({ + name: "prompt_sandbox", + arguments: { prompt: "list all files in the orgs directory" }, +}); -| 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). | +console.log(result.content); +``` From 05c455c18fa8c13f65e95764ffe9eef1ca7d1326 Mon Sep 17 00:00:00 2001 From: Recoup Agent Date: Tue, 24 Mar 2026 21:47:13 +0000 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20improve=20user=20journey=20?= =?UTF-8?q?=E2=80=94=20navigation,=20quickstart,=20MCP=20client=20configs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix navigation order: authentication now appears before MCP (you need auth before MCP) - Homepage: add integration path cards (REST/MCP/CLI), clearer "what you can build" framing - Quickstart: replace Tasks example (requires existing data) with Spotify search (works immediately); add MCP card in next steps - MCP page: add ready-to-paste config snippets for Claude Desktop, Cursor, and VS Code; move tool reference after connection guides - API reference introduction: remove duplicate auth/base URL content, link to authentication guide instead Co-Authored-By: Claude Sonnet 4.6 --- api-reference/introduction.mdx | 65 +++------------- docs.json | 4 +- index.mdx | 71 ++++++++--------- mcp.mdx | 109 +++++++++++++++++++------- quickstart.mdx | 135 +++++++++++---------------------- 5 files changed, 173 insertions(+), 211 deletions(-) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 057216c..95a557f 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,67 +1,20 @@ --- -title: 'Introduction' -description: 'API documentation for the Recoup platform - AI agents for the music industry' +title: 'API Reference' +description: 'Complete reference for all Recoup API endpoints.' --- -## Welcome +## Base URL + +``` +https://api.recoupable.com/api +``` -Welcome to the Recoup API documentation. Recoup is an AI agent platform for the music industry that provides artist analytics, fan segmentation, and AI-powered chat assistants. Build smarter song rollouts, create unforgettable fan experiences, and drive lasting artist growth. +All endpoints require authentication. See the [Authentication guide](/authentication) for how to pass your API key or Bearer token. - View the OpenAPI specification file on GitHub + View the full OpenAPI spec on GitHub - -## Base URL - -All API requests should be made to: - -```bash -https://api.recoupable.com/api -``` - -## Authentication - -All API endpoints are authenticated using an API key passed in the `x-api-key` header. - -### Getting Your API Key - -1. Navigate to the [API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account -3. Create a new API key and copy it immediately (it's only shown once) - -### Using Your API Key - -Include your API key in the `x-api-key` header for all requests: - -```bash -curl -X GET "https://api.recoupable.com/api/artists?accountId=YOUR_ACCOUNT_ID" \ - -H "Content-Type: application/json" \ - -H "x-api-key: YOUR_API_KEY" -``` - - -Keep your API key secure. Do not share it publicly or commit it to version control. - - -## Next Steps - - - - Get started with your first API request - - - Explore all available endpoints - - diff --git a/docs.json b/docs.json index 9361713..8754c4f 100644 --- a/docs.json +++ b/docs.json @@ -18,9 +18,9 @@ "pages": [ "index", "quickstart", - "cli", - "mcp", "authentication", + "mcp", + "cli", "api-reference/sandboxes/create" ] } diff --git a/index.mdx b/index.mdx index 05c0125..4a3edb0 100644 --- a/index.mdx +++ b/index.mdx @@ -1,71 +1,72 @@ --- title: "Recoup API Documentation" -description: "Use the Recoup API to build your record label." +description: "Build AI-powered tools for the music industry — artist analytics, fan segmentation, chat agents, and task automation." --- # Welcome to the Recoup API -Use the Recoup API to build your record label. Access artist analytics, fan segmentation, AI-powered chat, and task automation to power your music business. +Recoup is an AI agent platform for record labels, artists, and managers. Use the API to build intelligent automations, fan-facing experiences, and data-driven workflows on top of Recoup infrastructure. -## What is Recoup? +## Choose your integration path -Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools. - -This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more. - -## Get Started - - + - Get your API key and make your first request in minutes. + Make HTTP requests with your API key. Best for server-side integrations and custom tooling. + Connect AI agents (Claude, Cursor, VS Code) directly to Recoup tools via the Model Context Protocol. + + - Explore all available endpoints and integrations. + Run Recoup commands from your terminal. Useful for scripting and local development. -## Key Capabilities +## What you can build - AI-powered conversations with artist context. Stream responses or generate complete messages. + Pull social metrics, follower counts, and engagement data across Spotify, Instagram, X, and YouTube. - Comprehensive artist profiles with social metrics, follower counts, and engagement data across platforms. + Build streaming AI conversations with full artist context and persistent memory. - Organize and analyze fan bases by demographics, engagement levels, and behavior patterns. + Segment audiences by demographics, engagement, and behavior for targeted campaigns. - Schedule and automate recurring tasks with cron-based scheduling and AI-powered execution. + Schedule recurring AI-powered jobs — daily reports, fan outreach, content generation, and more. -## Platform Integrations +## Platform integrations - Search artists, albums, and tracks. + Search artists, albums, tracks. Pull top tracks and revenue data. - Scrape profiles and comments. + Scrape profiles and comments for fan intelligence. - Search tweets and trending topics. + Search tweets and trending topics in real time. -## Need Help? +## Need help? - Reach out to our team for assistance with the Recoup API. + Reach out to our team at agent@recoupable.com diff --git a/mcp.mdx b/mcp.mdx index 819049b..6a8d97d 100644 --- a/mcp.mdx +++ b/mcp.mdx @@ -23,17 +23,72 @@ The Recoup API exposes an MCP server that AI agents can connect to for tool use. https://recoup-api.vercel.app/mcp ``` -### Authentication +### Get an API key -All tools require an API key passed as a Bearer token: +Get your key from the [API Keys page](https://chat.recoupable.com/keys). All tools require your key as a Bearer token. +--- + +### Connect with Claude Desktop + +Add this to your `claude_desktop_config.json` (found at `~/Library/Application Support/Claude/` on macOS): + +```json +{ + "mcpServers": { + "recoup": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://recoup-api.vercel.app/mcp", + "--header", + "Authorization:${AUTH_HEADER}" + ], + "env": { + "AUTH_HEADER": "Bearer YOUR_API_KEY" + } + } + } +} ``` -Authorization: Bearer + +### Connect with Cursor + +Add this to `.cursor/mcp.json` in your project root, or to `~/.cursor/mcp.json` globally: + +```json +{ + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} ``` -Get a key from the [API Keys page](https://chat.recoupable.com/keys). +### Connect with VS Code + +Add this to `.vscode/mcp.json` in your project, or to your user settings: + +```json +{ + "servers": { + "recoup": { + "type": "http", + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` -### Connecting +### Connect programmatically (TypeScript SDK) ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; @@ -50,6 +105,28 @@ await client.connect(transport); --- +### Example: calling a tool + +```typescript +// Search for artist info +const result = await client.callTool({ + name: "search_web", + arguments: { query: "top hip hop releases this week", max_results: 5 }, +}); +console.log(result.content); +``` + +```typescript +// Run a prompt in a persistent sandbox +const result = await client.callTool({ + name: "prompt_sandbox", + arguments: { prompt: "list all files in the orgs directory" }, +}); +console.log(result.content); +``` + +--- + ### Tool Reference #### Artists @@ -175,25 +252,3 @@ await client.connect(transport); | Tool | Description | |------|-------------| | `get_local_time` | Get the current date and time for a given IANA timezone. | - ---- - -### Example: calling a tool - -```typescript -const result = await client.callTool({ - name: "search_web", - arguments: { query: "top hip hop releases this week", max_results: 5 }, -}); - -console.log(result.content); -``` - -```typescript -const result = await client.callTool({ - name: "prompt_sandbox", - arguments: { prompt: "list all files in the orgs directory" }, -}); - -console.log(result.content); -``` diff --git a/quickstart.mdx b/quickstart.mdx index cc7e37b..ebaa288 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,159 +1,112 @@ --- title: "Quickstart" -description: "Get your API key and make your first request to the Recoup API." +description: "Get your API key and make your first request to the Recoup API in under 5 minutes." --- ## Base URL -All API requests should be made to: - -```bash +``` https://api.recoupable.com/api ``` -## API Keys - -To access the Recoup API programmatically, you'll need to create an API key. - -### Step 1: Access the API Keys Management Page - -1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.com/keys) -2. Sign in with your account if you haven't already - -### Step 2: Create Your API Key +## Step 1: Get an API key -1. On the API Keys page, you'll see a form to create a new API key -2. Enter a descriptive name for your API key (e.g., "My Development Key", "Production API Key") -3. Click the "Create API Key" button +1. Go to [chat.recoupable.com/keys](https://chat.recoupable.com/keys) +2. Sign in to your account +3. Enter a name for your key (e.g. `"Development"`) and click **Create API Key** -Copy and securely store your API key immediately - it will only be shown once! +Copy your key immediately — it is only shown once and cannot be retrieved after creation. -### Step 3: Use Your API Key +## Step 2: Make your first request -Once you have your API key, include it in the `x-api-key` header for all authenticated requests. Here's a simple example that retrieves your scheduled tasks: +Search Spotify for an artist — this works immediately with no additional setup: ```bash cURL -curl -X GET "https://api.recoupable.com/api/tasks" \ - -H "Content-Type: application/json" \ +curl "https://api.recoupable.com/api/spotify/search?query=Drake&type=artist" \ -H "x-api-key: YOUR_API_KEY" ``` ```python Python import requests -headers = { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY" -} - response = requests.get( - "https://api.recoupable.com/api/tasks", - headers=headers + "https://api.recoupable.com/api/spotify/search", + params={"query": "Drake", "type": "artist"}, + headers={"x-api-key": "YOUR_API_KEY"}, ) print(response.json()) ``` ```javascript JavaScript -const response = await fetch("https://api.recoupable.com/api/tasks", { - headers: { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY", - }, -}); +const response = await fetch( + "https://api.recoupable.com/api/spotify/search?query=Drake&type=artist", + { headers: { "x-api-key": "YOUR_API_KEY" } } +); const data = await response.json(); console.log(data); ``` -```typescript TypeScript -interface Task { - id: string; - title: string; - prompt: string; - schedule: string; - account_id: string; - artist_account_id: string; - enabled: boolean; -} - -interface TasksResponse { - status: "success" | "error"; - tasks: Task[]; -} - -const response = await fetch("https://api.recoupable.com/api/tasks", { - headers: { - "Content-Type": "application/json", - "x-api-key": "YOUR_API_KEY", - }, -}); -const data: TasksResponse = await response.json(); -console.log(data.tasks); -``` - -**Example Response:** +**Example response:** ```json { "status": "success", - "tasks": [ + "artists": [ { - "id": "550e8400-e29b-41d4-a716-446655440000", - "title": "Daily Fan Report", - "prompt": "Generate a summary of new fans from the past 24 hours", - "schedule": "0 9 * * *", - "account_id": "123e4567-e89b-12d3-a456-426614174000", - "artist_account_id": "987fcdeb-51a2-3b4c-d5e6-789012345678", - "enabled": true + "id": "3TVXtAsR1Inumwj472S9r4", + "name": "Drake", + "followers": 88000000, + "popularity": 96, + "genres": ["canadian hip hop", "rap"], + "image": "https://i.scdn.co/image/..." } ] } ``` - -For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get). - - -## Next Steps - -With your API key ready, you can now: +## Step 3: Explore what's next - Fetch artist profiles, social accounts, and segments. - - - Access fan data across all connected social platforms. + Fetch an artist's full profile — social accounts, follower counts, and engagement data. - Build AI-powered conversations with artist context. + Build AI conversations with full artist context and streaming responses. - Schedule and automate recurring tasks. + Schedule recurring AI-powered jobs for reports, outreach, and content generation. + + + Connect Claude, Cursor, or VS Code directly to Recoup tools via MCP. -## Support +## Authentication reference + +All requests require your API key in the `x-api-key` header. For frontend apps using Privy, you can pass a Bearer token instead. See the [Authentication guide](/authentication) for full details. + +## Need help? -If you need help or have questions about the API, please contact our support team at [agent@recoupable.com](mailto:agent@recoupable.com). +Contact [agent@recoupable.com](mailto:agent@recoupable.com). From 52d8de93bceb0e9a71918b0f5791ccc6e9f3ce71 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Thu, 26 Mar 2026 01:00:45 -0400 Subject: [PATCH 3/4] docs: improve MCP page with professional Mintlify components and separate tool reference - Rewrite mcp.mdx with Tabs, Steps, CardGroup, Info/Warning callouts - Extract tool reference into dedicated mcp-tools.mdx page - Add mcp-tools to navigation in docs.json Made-with: Cursor --- docs.json | 1 + mcp-tools.mdx | 136 ++++++++++++++++++ mcp.mdx | 383 ++++++++++++++++++++------------------------------ 3 files changed, 290 insertions(+), 230 deletions(-) create mode 100644 mcp-tools.mdx diff --git a/docs.json b/docs.json index 8754c4f..88d3519 100644 --- a/docs.json +++ b/docs.json @@ -20,6 +20,7 @@ "quickstart", "authentication", "mcp", + "mcp-tools", "cli", "api-reference/sandboxes/create" ] diff --git a/mcp-tools.mdx b/mcp-tools.mdx new file mode 100644 index 0000000..f006c08 --- /dev/null +++ b/mcp-tools.mdx @@ -0,0 +1,136 @@ +--- +title: "MCP Tool Reference" +description: "Complete list of tools available through the Recoup MCP server." +--- + +Every tool listed here is callable through the [Recoup MCP server](/mcp). Connect your AI agent, then call any tool by name. + + + All tools require a valid API key. Get yours from the [API Keys page](https://chat.recoupable.com/keys). + + +--- + +## Artists + +| Tool | Description | +|------|-------------| +| `create_new_artist` | Create a new artist account. | +| `get_artist_socials` | Get all social profiles linked to an artist. | +| `update_artist_socials` | Set social profile URLs for an artist (platform auto-detected). | +| `artist_deep_research` | Run comprehensive research on an artist across platforms. | +| `update_account_info` | Update an artist's profile info (name, image, instructions, knowledge base). | + +## Chats + +| Tool | Description | +|------|-------------| +| `get_chats` | List chat conversations, optionally filtered by account or artist. | +| `compact_chats` | Summarize one or more chat conversations into concise notes. | + +## Tasks + +| Tool | Description | +|------|-------------| +| `get_tasks` | List scheduled tasks, optionally filtered by account, artist, or enabled status. | +| `create_task` | Create a new scheduled task. | +| `update_task` | Update an existing task. | +| `delete_task` | Delete a task by ID. | +| `get_task_run_status` | Get the status of a Trigger.dev background task run. | + +## Pulses + +| Tool | Description | +|------|-------------| +| `get_pulses` | Get pulse statuses for accounts. | +| `update_pulse` | Enable or disable the pulse for the authenticated account. | + +## Catalogs & Songs + +| Tool | Description | +|------|-------------| +| `select_catalogs` | List catalogs for an account. Call this first before recommending songs. | +| `select_catalog_songs` | Find songs from a catalog matching given criteria. | +| `insert_catalog_songs` | Add songs to a catalog by ISRC in batch. | + +## Spotify + +| Tool | Description | +|------|-------------| +| `get_spotify_search` | Search Spotify for artists, albums, tracks, playlists, shows, or episodes. | +| `get_spotify_artist_albums` | Get an artist's albums from Spotify. | +| `get_spotify_artist_top_tracks` | Get an artist's top tracks by market. | +| `get_spotify_album` | Get details for a single Spotify album. | +| `spotify_deep_research` | Deep-research an artist using their Spotify ID. | + +## YouTube + +| Tool | Description | +|------|-------------| +| `youtube_login` | Check YouTube authentication status for an artist. | +| `get_youtube_channels` | Get YouTube channel info for an artist. | +| `get_youtube_channel_video_list` | List videos from a YouTube channel's uploads playlist. | +| `get_youtube_revenue` | Get estimated YouTube revenue data for a date range. | +| `set_youtube_thumbnail` | Set a custom thumbnail for a YouTube video. | + +## Search & Research + +| Tool | Description | +|------|-------------| +| `search_web` | Search the web for real-time information via Perplexity. | +| `search_google_images` | Search Google Images for photos or visual content. | +| `web_deep_research` | Deep web research using Perplexity's `sonar-deep-research` model. | + +## Images + +| Tool | Description | +|------|-------------| +| `generate_image` | Generate an image from a text prompt. | +| `edit_image` | Edit an existing image using a text prompt. | + +## Video + +| Tool | Description | +|------|-------------| +| `generate_sora_2_video` | Generate a video from a text prompt using OpenAI Sora 2. | +| `retrieve_sora_2_video` | Get the status and details of a video generation job. | +| `retrieve_sora_2_video_content` | Download the rendered video content. | + +## Audio + +| Tool | Description | +|------|-------------| +| `transcribe_audio` | Transcribe an audio file using OpenAI Whisper (MP3, WAV, M4A, WebM). | +| `analyze_music` | Analyze a track using the Music Flamingo model (mood tags, metadata, sync briefs, etc.). | + +## Files & Knowledge + +| Tool | Description | +|------|-------------| +| `create_knowledge_base` | Save a plain-text knowledge base entry to an artist's permanent storage. | +| `generate_txt_file` | Create a downloadable TXT file stored on Arweave. | + +## Communication + +| Tool | Description | +|------|-------------| +| `send_email` | Send an email via the Resend API. | +| `contact_team` | Send a support message to the Recoup team. | + +## Segments + +| Tool | Description | +|------|-------------| +| `create_segments` | Analyze fan data and generate audience segments for an artist. | + +## Sandboxes + +| Tool | Description | +|------|-------------| +| `prompt_sandbox` | Run an OpenClaw prompt inside a persistent per-account sandbox. Returns `stdout`, `stderr`, `exitCode`, and the sandbox ID. | + +## Utilities + +| Tool | Description | +|------|-------------| +| `get_local_time` | Get the current date and time for a given IANA timezone. | diff --git a/mcp.mdx b/mcp.mdx index 6a8d97d..cc7aad9 100644 --- a/mcp.mdx +++ b/mcp.mdx @@ -3,11 +3,24 @@ title: "MCP Servers" description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP)." --- -Recoup exposes two MCP servers: one for **searching these docs**, and one for **calling Recoup tools** from your AI agent. + + [MCP (Model Context Protocol)](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external tools and data sources. Recoup exposes two MCP servers you can use today. + + +## Choose your MCP server + + + + Search and read the Recoup API docs directly from your AI assistant — powered by Mintlify. + + + Call 40+ Recoup tools (artists, Spotify, video, search, sandboxes, and more) from your AI agent. + + --- -## 1. Docs Search MCP +## Docs Search MCP Every page in these docs includes an **MCP** button in the contextual menu (top-right of each page). Clicking it gives you a ready-to-use config snippet to add the Recoup docs as an MCP source in Claude, Cursor, VS Code, or any MCP-compatible client. @@ -15,240 +28,150 @@ This server is powered by Mintlify and lets AI assistants search and read the Re --- -## 2. Recoup API MCP Server +## Recoup API MCP Server -The Recoup API exposes an MCP server that AI agents can connect to for tool use. The server is available at: +The Recoup API exposes an MCP server that AI agents can connect to for tool use: ``` https://recoup-api.vercel.app/mcp ``` -### Get an API key - -Get your key from the [API Keys page](https://chat.recoupable.com/keys). All tools require your key as a Bearer token. - ---- - -### Connect with Claude Desktop - -Add this to your `claude_desktop_config.json` (found at `~/Library/Application Support/Claude/` on macOS): - -```json -{ - "mcpServers": { - "recoup": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "https://recoup-api.vercel.app/mcp", - "--header", - "Authorization:${AUTH_HEADER}" - ], - "env": { - "AUTH_HEADER": "Bearer YOUR_API_KEY" - } - } - } -} -``` - -### Connect with Cursor - -Add this to `.cursor/mcp.json` in your project root, or to `~/.cursor/mcp.json` globally: - -```json -{ - "mcpServers": { - "recoup": { - "url": "https://recoup-api.vercel.app/mcp", - "headers": { - "Authorization": "Bearer YOUR_API_KEY" - } - } - } -} -``` - -### Connect with VS Code - -Add this to `.vscode/mcp.json` in your project, or to your user settings: - -```json -{ - "servers": { - "recoup": { - "type": "http", - "url": "https://recoup-api.vercel.app/mcp", - "headers": { - "Authorization": "Bearer YOUR_API_KEY" - } - } - } -} -``` - -### Connect programmatically (TypeScript SDK) - -```typescript -import { Client } from "@modelcontextprotocol/sdk/client/index.js"; -import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; - -const transport = new StreamableHTTPClientTransport( - new URL("https://recoup-api.vercel.app/mcp"), - { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, -); - -const client = new Client({ name: "my-agent", version: "1.0.0" }); -await client.connect(transport); -``` - ---- - -### Example: calling a tool - -```typescript -// Search for artist info -const result = await client.callTool({ - name: "search_web", - arguments: { query: "top hip hop releases this week", max_results: 5 }, -}); -console.log(result.content); -``` - -```typescript -// Run a prompt in a persistent sandbox -const result = await client.callTool({ - name: "prompt_sandbox", - arguments: { prompt: "list all files in the orgs directory" }, -}); -console.log(result.content); -``` +### Setup + + + + Go to the [API Keys page](https://chat.recoupable.com/keys), sign in, and create a new key. + + + Copy your key immediately — it is only shown once and cannot be retrieved after creation. + + + + Pick your AI client below and paste the config, replacing `YOUR_API_KEY` with your actual key. + + + + Add to your `claude_desktop_config.json` (found at `~/Library/Application Support/Claude/` on macOS): + + ```json + { + "mcpServers": { + "recoup": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://recoup-api.vercel.app/mcp", + "--header", + "Authorization:${AUTH_HEADER}" + ], + "env": { + "AUTH_HEADER": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + Add to `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` globally: + + ```json + { + "mcpServers": { + "recoup": { + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + Add to `.vscode/mcp.json` in your project, or to your user settings: + + ```json + { + "servers": { + "recoup": { + "type": "http", + "url": "https://recoup-api.vercel.app/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } + } + ``` + + + Install the MCP SDK and connect programmatically: + + ```typescript + import { Client } from "@modelcontextprotocol/sdk/client/index.js"; + import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; + + const transport = new StreamableHTTPClientTransport( + new URL("https://recoup-api.vercel.app/mcp"), + { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, + ); + + const client = new Client({ name: "my-agent", version: "1.0.0" }); + await client.connect(transport); + ``` + + + + + Once connected, your AI agent can call any Recoup tool. Here are two examples using the TypeScript SDK: + + + + ```typescript Search the web + const result = await client.callTool({ + name: "search_web", + arguments: { query: "top hip hop releases this week", max_results: 5 }, + }); + console.log(result.content); + ``` + + ```typescript Run a sandbox prompt + const result = await client.callTool({ + name: "prompt_sandbox", + arguments: { prompt: "list all files in the orgs directory" }, + }); + console.log(result.content); + ``` + + + + --- -### Tool Reference - -#### Artists - -| Tool | Description | -|------|-------------| -| `create_new_artist` | Create a new artist account. | -| `get_artist_socials` | Get all social profiles linked to an artist. | -| `update_artist_socials` | Set social profile URLs for an artist (platform auto-detected). | -| `artist_deep_research` | Run comprehensive research on an artist across platforms. | -| `update_account_info` | Update an artist's profile info (name, image, instructions, knowledge base). | - -#### Chats - -| Tool | Description | -|------|-------------| -| `get_chats` | List chat conversations, optionally filtered by account or artist. | -| `compact_chats` | Summarize one or more chat conversations into concise notes. | - -#### Tasks - -| Tool | Description | -|------|-------------| -| `get_tasks` | List scheduled tasks, optionally filtered by account, artist, or enabled status. | -| `create_task` | Create a new scheduled task. | -| `update_task` | Update an existing task. | -| `delete_task` | Delete a task by ID. | -| `get_task_run_status` | Get the status of a Trigger.dev background task run. | - -#### Pulses - -| Tool | Description | -|------|-------------| -| `get_pulses` | Get pulse statuses for accounts. | -| `update_pulse` | Enable or disable the pulse for the authenticated account. | - -#### Catalogs & Songs - -| Tool | Description | -|------|-------------| -| `select_catalogs` | List catalogs for an account. Call this first before recommending songs. | -| `select_catalog_songs` | Find songs from a catalog matching given criteria. | -| `insert_catalog_songs` | Add songs to a catalog by ISRC in batch. | - -#### Spotify - -| Tool | Description | -|------|-------------| -| `get_spotify_search` | Search Spotify for artists, albums, tracks, playlists, shows, or episodes. | -| `get_spotify_artist_albums` | Get an artist's albums from Spotify. | -| `get_spotify_artist_top_tracks` | Get an artist's top tracks by market. | -| `get_spotify_album` | Get details for a single Spotify album. | -| `spotify_deep_research` | Deep-research an artist using their Spotify ID. | - -#### YouTube - -| Tool | Description | -|------|-------------| -| `youtube_login` | Check YouTube authentication status for an artist. | -| `get_youtube_channels` | Get YouTube channel info for an artist. | -| `get_youtube_channel_video_list` | List videos from a YouTube channel's uploads playlist. | -| `get_youtube_revenue` | Get estimated YouTube revenue data for a date range. | -| `set_youtube_thumbnail` | Set a custom thumbnail for a YouTube video. | - -#### Search & Research - -| Tool | Description | -|------|-------------| -| `search_web` | Search the web for real-time information via Perplexity. | -| `search_google_images` | Search Google Images for photos or visual content. | -| `web_deep_research` | Deep web research using Perplexity's `sonar-deep-research` model. | - -#### Images - -| Tool | Description | -|------|-------------| -| `generate_image` | Generate an image from a text prompt. | -| `edit_image` | Edit an existing image using a text prompt. | - -#### Video - -| Tool | Description | -|------|-------------| -| `generate_sora_2_video` | Generate a video from a text prompt using OpenAI Sora 2. | -| `retrieve_sora_2_video` | Get the status and details of a video generation job. | -| `retrieve_sora_2_video_content` | Download the rendered video content. | - -#### Audio - -| Tool | Description | -|------|-------------| -| `transcribe_audio` | Transcribe an audio file using OpenAI Whisper (MP3, WAV, M4A, WebM). | -| `analyze_music` | Analyze a track using the Music Flamingo model (mood tags, metadata, sync briefs, etc.). | - -#### Files & Knowledge - -| Tool | Description | -|------|-------------| -| `create_knowledge_base` | Save a plain-text knowledge base entry to an artist's permanent storage. | -| `generate_txt_file` | Create a downloadable TXT file stored on Arweave. | - -#### Communication - -| Tool | Description | -|------|-------------| -| `send_email` | Send an email via the Resend API. | -| `contact_team` | Send a support message to the Recoup team. | - -#### Segments - -| Tool | Description | -|------|-------------| -| `create_segments` | Analyze fan data and generate audience segments for an artist. | - -#### Sandboxes - -| Tool | Description | -|------|-------------| -| `prompt_sandbox` | Run an OpenClaw prompt inside a persistent per-account sandbox. Returns `stdout`, `stderr`, `exitCode`, and the sandbox ID. | - -#### Utilities - -| Tool | Description | -|------|-------------| -| `get_local_time` | Get the current date and time for a given IANA timezone. | +## Available tools + +The Recoup MCP server exposes 40+ tools across these categories. See the [full tool reference](/mcp-tools) for details on every tool. + + + + Create artists, manage socials, run deep research. + + + Search, top tracks, albums, and deep research. + + + Channels, videos, revenue, and thumbnails. + + + Web search, image search, and deep research. + + + Generate and edit images, create Sora 2 videos. + + + Run prompts in persistent per-account sandboxes. + + From 2a2f366a61d816ee88435fbfa4f3b721b888114e Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Thu, 26 Mar 2026 01:02:32 -0400 Subject: [PATCH 4/4] fix: use correct Spotify search parameter `q` instead of `query` The OpenAPI spec defines the parameter as `q`, so the quickstart examples would return 400 errors with `query`. Made-with: Cursor --- quickstart.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index ebaa288..fb0d409 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -26,7 +26,7 @@ Search Spotify for an artist — this works immediately with no additional setup ```bash cURL -curl "https://api.recoupable.com/api/spotify/search?query=Drake&type=artist" \ +curl "https://api.recoupable.com/api/spotify/search?q=Drake&type=artist" \ -H "x-api-key: YOUR_API_KEY" ``` @@ -35,7 +35,7 @@ import requests response = requests.get( "https://api.recoupable.com/api/spotify/search", - params={"query": "Drake", "type": "artist"}, + params={"q": "Drake", "type": "artist"}, headers={"x-api-key": "YOUR_API_KEY"}, ) print(response.json()) @@ -43,7 +43,7 @@ print(response.json()) ```javascript JavaScript const response = await fetch( - "https://api.recoupable.com/api/spotify/search?query=Drake&type=artist", + "https://api.recoupable.com/api/spotify/search?q=Drake&type=artist", { headers: { "x-api-key": "YOUR_API_KEY" } } ); const data = await response.json();