Model Context Protocol (MCP) Tools
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Model Context Protocol (MCP) Tools in the Recoupable API provide a standardized interface for AI agents to interact with external systems, perform deep research, and manage artist data. The architecture follows a DRY (Don't Repeat Yourself) principle where tools share underlying business logic with standard REST API endpoints. This ensures consistent behavior whether a task is initiated via a direct API call or an AI agent's tool invocation.
Sources: CLAUDE.md:323-326, lib/chat/const.ts:1-10
Architecture and Design Patterns
The MCP implementation utilizes the @modelcontextprotocol/sdk to register and manage tools. The system is designed to be "Sandbox-First," where complex tasks involving files, code, or data analysis are directed to a persistent sandbox environment via the prompt_sandbox tool. Other MCP tools are specialized for single-purpose lookups or specific on-chain operations.
Shared Logic Pattern
To maintain consistency, MCP tools and REST API routes delegate their core functionality to domain-specific functions.
Sources: CLAUDE.md:330-345, lib/chat/const.ts:10-20
Tool Registration
Tools are registered on an McpServer instance using Zod for input schema validation. Each registration defines a unique tool name, a description for the AI, and an asynchronous handler function.
Sources: lib/mcp/tools/files/registerGenerateTxtFileTool.ts:25-30, CLAUDE.md:367-375
Core MCP Tools
The following table summarizes key MCP tools available in the system:
| Tool Name | Description | Key Parameters |
|---|---|---|
web_deep_research | Performs comprehensive, multi-source analysis using Perplexity's sonar models. | messages (Array) |
generate_txt_file | Creates a downloadable TXT file stored on Arweave. | contents (String) |
create_knowledge_base | Saves plain-text notes/bios to an artist's permanent storage. | artistId, knowledgeBaseText |
prompt_sandbox | Primary tool for files, code, and structured release management. | Varies |
Sources: lib/mcp/tools/registerWebDeepResearchTool.ts:31-38, lib/mcp/tools/files/registerGenerateTxtFileTool.ts:27-31, lib/mcp/tools/files/registerCreateKnowledgeBaseTool.ts:32-34, lib/chat/const.ts:10-18
Web Deep Research
The web_deep_research tool leverages the sonar-deep-research model to synthesize information from various sources. It is specifically designed for complex queries that require more extensive exploration than a standard web search.
File and Knowledge Management
The system provides tools for permanent data storage on Arweave. The create_knowledge_base tool is restricted to unstructured data like bios and reference notes, while structured data like release plans must be handled by the sandbox.
Sources: lib/mcp/tools/files/registerCreateKnowledgeBaseTool.ts:33-35, lib/chat/const.ts:20-23
Authentication and Security
Security is managed via a centralized resolution pattern. Tools must never accept a raw account_id from the AI. Instead, they derive the ID from the RequestHandlerExtra metadata.
- Extraction: Extract
authInfofrom theextraparameter. - Resolution: Use
resolveAccountId()to handle validation and organization-key overrides. - Validation: Ensure the user has access to the requested artist or workspace context.
Sources: CLAUDE.md:275-295
Tool Chains and Orchestration
Certain complex operations, such as create_new_artist, are orchestrated through defined "Tool Chains." These chains define a sequence of tools that the agent is encouraged to use in order.
Example: create_new_artist Chain
get_spotify_search: Identify the artist.update_account_info: Populate basic metadata.generate_txt_file: Create an initial knowledge base report.update_account_info: Link the generated Arweave URL to the account.youtube_login: Authenticate for social management.
Sources: lib/chat/toolChains/tests/toolChains.test.ts:75-125
Implementation Utilities
| Function | File | Purpose |
|---|---|---|
getMcpTools | lib/mcp/getMcpTools.ts | Creates an MCP client using HTTP transport and Bearer tokens. |
getToolResultSuccess | lib/mcp/getToolResultSuccess.ts | Wraps successful data in the MCP-required content structure. |
getToolResultError | lib/mcp/getToolResultError.ts | Wraps error messages for the agent. |
getCallToolResult | lib/mcp/getCallToolResult.ts | Standardizes text content responses. |
Sources: lib/mcp/getMcpTools.ts:1-20, lib/mcp/getCallToolResult.ts:1-20, CLAUDE.md:395-400
Conclusion
The MCP Tools system acts as the "hands" of the Recoup AI assistant. By leveraging Arweave for permanent storage, Perplexity for research, and a sandbox for computation, it enables the agent to move beyond simple chat into active music industry management. The strict adherence to DRY patterns and centralized authentication ensures the system remains secure and maintainable as new tools are added.