CNVRT MCP Server 🤖

Model Context Protocol server for AI agent integration with CNVRT media conversion services

This MCP server enables AI agents to seamlessly convert and transcribe media using the CNVRT service with automatic x402 micropayments.

🌟 Features

• Natural Language Interface: Agents interact using simple prompts
• Automatic Payments: x402 micropayments handled transparently
• Multi-Network: Supports both Base and Solana payments
• Smart Routing: Automatically selects optimal network for the agent
• Full Tool Suite: Convert, transcribe URLs, transcribe files
• Error Handling: Robust error messages and retry logic

🚀 Quick Start

Easy Installation (Recommended)

# Install globally from npm
npm install -g @cnvrt/mcp-server

# Run auto-setup (Interactive - takes 2 minutes)
npx cnvrt-setup

That's it! The setup script will:

1. Detect your AI platform (Claude Desktop, etc.)
2. Prompt for network preference (Base or Solana)
3. Configure service URLs
4. Create .env file
5. Update MCP configuration file
6. Show usage instructions

Setup time: 2 minutes!

Manual Installation

If you prefer manual setup:

# Install from npm (when published)
npm install -g @cnvrt/mcp-server

# Or clone and install locally
git clone https://github.com/yourusername/convrt.git
cd convrt/mcp-server
npm install

Manual Configuration

Create a .env file:

# MCP Server Configuration
MCP_PORT=3001

# CNVRT Service URLs
BASE_SERVICE_URL=https://cnvrt-base.railway.app
SOLANA_SERVICE_URL=https://cnvrt-solana.railway.app

# x402 Payment Settings
X402_ENABLED=true

# Wallet Configuration
BASE_PRIVATE_KEY=0x...  # Your Base wallet private key
SOLANA_PRIVATE_KEY=...  # Your Solana wallet private key (base58)

Running

npm start

🔌 Connecting to AI Agents

Claude Desktop

Edit your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cnvrt": {
      "command": "node",
      "args": ["/absolute/path/to/convrt/mcp-server/index.js"],
      "env": {
        "BASE_SERVICE_URL": "https://cnvrt-base.railway.app",
        "SOLANA_SERVICE_URL": "https://cnvrt-solana.railway.app",
        "X402_ENABLED": "true",
        "BASE_PRIVATE_KEY": "0x...",
        "SOLANA_PRIVATE_KEY": "..."
      }
    }
  }
}

Using NPM package:

{
  "mcpServers": {
    "cnvrt": {
      "command": "npx",
      "args": ["@cnvrt/mcp-server"],
      "env": {
        "BASE_SERVICE_URL": "https://cnvrt-base.railway.app",
        "SOLANA_SERVICE_URL": "https://cnvrt-solana.railway.app",
        "X402_ENABLED": "true",
        "BASE_PRIVATE_KEY": "0x...",
        "SOLANA_PRIVATE_KEY": "..."
      }
    }
  }
}

Other MCP Clients

The server implements the standard MCP protocol and works with any compatible client:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['/path/to/mcp-server/index.js'],
  env: {
    BASE_SERVICE_URL: 'https://cnvrt-base.railway.app',
    SOLANA_SERVICE_URL: 'https://cnvrt-solana.railway.app',
    X402_ENABLED: 'true',
    BASE_PRIVATE_KEY: '0x...',
    SOLANA_PRIVATE_KEY: '...'
  }
});

const client = new Client({
  name: 'my-agent',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

🤖 Agent-Friendly Features

CNVRT is designed to be ultra-friendly for AI agents with several FREE helper endpoints:

✅ Pre-Flight Validation (FREE)

Endpoint: POST /api/validate

Validate requests before paying to avoid wasted costs:

{
  "url": "https://youtube.com/watch?v=xyz",
  "format": "mp3"
}

Returns validation status, estimated cost, and suggestions.

💰 Cost Estimator (FREE)

Endpoint: POST /api/estimate-cost

Know exact costs before making requests:

{
  "format": "mp3",
  "features": ["asr", "sentiment"]
}

Returns total cost breakdown and estimated time.

🎯 Format Detection (FREE)

Endpoint: POST /api/detect-format

Auto-detect formats and get smart suggestions:

{
  "url": "https://example.com/photo.jpg"
}

Returns detected format, category, and optimization suggestions.

📊 Usage Analytics (FREE)

Endpoint: GET /api/usage
Header: X-Agent-ID: your-agent-id

Track your success rate, costs, and top errors.

🔍 Batch Validation (FREE)

Endpoint: POST /api/validate/batch

Validate up to 50 requests at once to identify issues before paying.

🏥 Health Check Headers

Every response includes service health headers:

• X-Service-Health: healthy/degraded/unhealthy
• X-FFmpeg-Available: healthy/unhealthy
• X-OpenAI-Available: healthy/unhealthy
• X-GPU-Enabled: true/false

🛡️ Error Handling with Actions

All errors include suggested actions to fix them:

{
  "error": {
    "code": "CNVRT_FORMAT_UNSUPPORTED",
    "message": "Format 'mpeg' not supported",
    "retryable": false,
    "suggestedAction": {
      "action": "CHANGE_FORMAT",
      "steps": [
        "Check supported formats at GET /api/formats",
        "Use POST /api/detect-format for suggestions",
        "Common formats: mp3, mp4, jpg, png, webp, pdf, txt, html"
      ]
    }
  }
}

🛠️ Available Tools

1. convert_media - Universal File Conversion

Convert ANY file type to any other format - media, images, documents, archives.

Parameters:

{
  "url": "https://www.youtube.com/watch?v=...",  // For media URLs
  "file": "/path/to/file.jpg",  // OR for local files
  "format": "mp3",  // For URL conversion
  "from": "jpg",  // For file conversion
  "to": "png",  // For file conversion
  "quality": "best",
  "network": "base"
}

Supported Conversions:

• Media: YouTube, TikTok → MP3, MP4, WAV, AVI, WebM
• Images: JPG ↔ PNG, WebP, GIF, BMP, TIFF, AVIF
• Documents: DOCX ↔ PDF, TXT, HTML, Markdown
• Archives: ZIP, RAR, 7Z, TAR, GZ (create/extract)

Example Prompts:

• "Convert this YouTube video to MP3"
• "Convert this PNG to WebP"
• "Convert this DOCX to PDF"
• "Extract this ZIP file"

2. transcribe_media - Transcribe from URL

Transcribe audio/video from URLs using OpenAI Whisper (95%+ accuracy).

Parameters:

{
  "url": "https://example.com/podcast.mp3",
  "network": "base"
}

Example Prompts:

• "Transcribe this podcast"
• "What does this YouTube video say?"
• "Convert this audio to text"

3. transcribe_file - Transcribe Local Files

Transcribe uploaded audio/video files.

Parameters:

{
  "filePath": "/path/to/audio.mp3",
  "network": "base"
}

Example Prompts:

• "Transcribe this file: recording.mp3"
• "Get text from my voice memo"

4. analyze_livestream - Real-Time Stream Analysis ⭐

Process live streams with AI features (ASR, vision, diarization, sentiment).

Parameters:

{
  "url": "https://twitch.tv/channel",  // For public streams
  "source_type": "url",  // OR "agent_capture" for device capture
  "features": ["asr", "vision", "diarization"],
  "latency_target_ms": 1000,
  "webhooks": [...],  // Optional filtered webhooks
  "network": "base"
}

Features:

• asr: Real-time speech-to-text
• vision: Scene detection with GPT-4o
• ocr: Text extraction from frames
• diarization: Speaker identification + sentiment
• embeddings: Semantic search vectors

Two Modes:

1. URL: Public streams (Twitch, YouTube Live, TikTok)
2. Agent Capture: Private media (Discord, Zoom, screen)

Example Prompts:

• "Analyze this Twitch stream in real-time"
• "Start capturing my screen and transcribe"
• "Monitor this meeting for action items"

5. search_livestream - Search Transcripts ⭐

Find specific moments in transcripts with keyword/speaker/sentiment filters.

Parameters:

{
  "stream_id": "str_xyz123",
  "query": "budget",
  "speaker": "Speaker A",  // Optional
  "sentiment": "negative",  // Optional
  "limit": 20,
  "network": "base"
}

Example Prompts:

• "Find all mentions of 'budget'"
• "What did Speaker A say that was negative?"
• "Search for 'deadline' in this meeting"

6. generate_clip - Create Video Clips ⭐

Generate shareable video clips from livestreams with optional captions.

Parameters:

{
  "stream_id": "str_xyz123",
  "start": 145.2,
  "duration": 30,
  "add_captions": true,
  "format": "mp4",
  "network": "base"
}

Example Prompts:

• "Create a 30-second clip starting at 2:45"
• "Generate clip with captions at this timestamp"
• "Make shareable clips for all key moments"

7. end_live_analysis - End Stream Session ⭐

Stop livestream analysis and get final statistics.

Parameters:

{
  "stream_id": "str_xyz123",
  "network": "base"
}

Example Prompts:

• "End the analysis session"
• "Stop analyzing and show stats"
• "Close this stream and give me the summary"

8. extract_data - Universal Data Extraction 🆕

Extract structured data from any unstructured media.

Parameters:

{
  "file": "/path/to/file.pdf",  // OR url
  "extract_type": "tables",  // text, tables, forms, metadata, speech, embeddings
  "options": {...},
  "network": "base"
}

Extraction Types:

• text: Plain text from any document/image
• tables: Structured JSON/CSV from PDFs
• forms: Form field detection
• metadata: File properties (duration, codec, resolution)
• speech: Audio transcription
• embeddings: Semantic vectors for RAG

Example Prompts:

• "Extract tables from this invoice PDF"
• "Get metadata from this video file"
• "Generate embeddings for this document"
• "Pull text from this screenshot"

9. analyze_image - Raw Artifact Extraction 🆕

Extract OCR text and detect objects (NO reasoning - raw artifacts only).

Parameters:

{
  "url": "https://example.com/image.jpg",  // OR file (base64)
  "detail": "high",  // low, high, auto
  "network": "base"
}

Example Prompts:

• "What text is in this image?"
• "Extract objects from this screenshot"
• "Read text from this photo"

🌐 Network Selection

The MCP server intelligently routes requests to the appropriate CNVRT service:

Automatic Network Detection

If network parameter is omitted, the server:

1. Checks if agent has specified a preference
2. Defaults to Base network (EVM compatible)
3. Falls back to Solana if Base is unavailable

Manual Network Selection

Specify network: "base" or network: "solana" in tool parameters:

"Convert this video using Solana: https://youtube.com/..."

The agent will extract the network preference and route accordingly.

Service URLs

Configure different service URLs per network:

BASE_SERVICE_URL=https://cnvrt-base.railway.app
SOLANA_SERVICE_URL=https://cnvrt-solana.railway.app

The MCP server uses getServiceUrl(network) to determine the correct endpoint.

💰 Payment Handling

How x402 Payments Work

1. Agent calls tool → MCP server makes API request
2. 402 Response → Service requires payment
3. Automatic payment → MCP signs and submits payment
4. Retry request → Service grants access
5. Return result → Agent receives data

Payment Configuration

Base (EVM):

BASE_PRIVATE_KEY=0x...  # Hex-encoded private key

Solana:

SOLANA_PRIVATE_KEY=...  # Base58-encoded private key

Wallet Requirements

• Base: Must have USDC on Base mainnet
• Solana: Must have SOL (for fees) and USDC on Solana mainnet

Get Test Funds:

• Base USDC: Bridge from Ethereum or buy on Coinbase
• Solana USDC: Buy on Coinbase or Jupiter

Disabling Payments (Testing)

For testing without real payments:

X402_ENABLED=false

The MCP server will skip payment logic (only works with test/dev CNVRT services).

🔒 Security Best Practices

Private Key Management

DO:

• ✅ Store private keys in environment variables
• ✅ Use dedicated wallets with limited funds for MCP
• ✅ Rotate keys periodically
• ✅ Use .env files excluded from git (.gitignore)

DON'T:

• ❌ Hardcode private keys in source code
• ❌ Commit .env files to version control
• ❌ Use main wallets with large balances
• ❌ Share private keys in logs or error messages

Recommended Setup

# Create dedicated CNVRT payment wallets
# Fund with small amounts (e.g., $10 USDC per network)
# Use these keys ONLY for MCP server

BASE_PRIVATE_KEY=0x...     # Low-balance Base wallet
SOLANA_PRIVATE_KEY=...     # Low-balance Solana wallet

Monitoring

Check wallet balances periodically:

# Base USDC balance
cast balance --rpc-url https://mainnet.base.org 0x... --erc20 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

# Solana USDC balance
spl-token balance EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

🧪 Testing

Test the MCP Server

npm test

Test with Claude Desktop

1. Configure Claude Desktop (see above)
2. Restart Claude Desktop
3. Start a new conversation
4. Try example prompts:

"Use the CNVRT tool to convert this video: https://youtube.com/watch?v=dQw4w9WgXcQ"
"Transcribe this audio: https://example.com/audio.mp3"

Test Direct Tool Calls

# Test convert_media tool
curl -X POST http://localhost:3001/tools/convert_media \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "format": "mp3",
    "quality": "best",
    "network": "base"
  }'

🐛 Troubleshooting

MCP Server Won't Start

Error: Missing environment variables

Solution: Check your .env file has all required variables:

BASE_SERVICE_URL=...
SOLANA_SERVICE_URL=...
BASE_PRIVATE_KEY=...
SOLANA_PRIVATE_KEY=...

Claude Desktop Not Detecting Server

1. Check config path: Verify claude_desktop_config.json location
2. Restart Claude: Fully quit and reopen Claude Desktop
3. Check logs: Look for MCP server errors in Claude's logs
4. Test manually: Run node index.js and check for errors

Payment Failures

Error: Failed to process payment

Possible Causes:

• Insufficient USDC balance
• Insufficient SOL/ETH for gas fees
• Invalid private key format
• Network congestion

Solutions:

1. Check wallet balances
2. Verify private key format (hex for Base, base58 for Solana)
3. Test with smaller requests first
4. Check network status

Network Errors

Error: Failed to connect to CNVRT service

Solutions:

1. Verify service URLs are correct and accessible
2. Check internet connection
3. Try alternative network (Base ↔ Solana)
4. Check CNVRT service status

📊 Monitoring & Logging

Enable Debug Logging

DEBUG=cnvrt:* npm start

Log Locations

• stdout: Real-time tool calls and responses
• stderr: Errors and warnings
• Claude logs: See Claude Desktop documentation

Example Logs

🤖 MCP Server: CNVRT Media Converter v1.0.0
   Port: 3001
   Base Service: https://cnvrt-base.railway.app
   Solana Service: https://cnvrt-solana.railway.app
   x402 Enabled: true

✅ Tool called: convert_media
   Network: base
   URL: https://youtube.com/watch?v=...
   Format: mp3

💳 Processing x402 payment...
   Network: base
   Amount: $0.01 USDC
   
✅ Payment successful
   Transaction: 0x...
   
🎵 Conversion complete
   Download URL: https://cnvrt.../output.mp3
   Duration: 240s
   Size: 3.8 MB

🚀 Advanced Usage

Custom Service Endpoints

Point to your self-hosted CNVRT instances:

BASE_SERVICE_URL=http://localhost:3000
SOLANA_SERVICE_URL=http://localhost:3001

Multiple Agent Support

Run multiple MCP servers for different agents:

# Agent 1 (Claude)
MCP_PORT=3001 npm start

# Agent 2 (Another AI)
MCP_PORT=3002 npm start

Programmatic Usage

Use the MCP server programmatically in your own agent:

import { MCPServer } from './mcp-server/index.js';

const server = new MCPServer({
  baseServiceUrl: 'https://cnvrt-base.railway.app',
  solanaServiceUrl: 'https://cnvrt-solana.railway.app',
  x402Enabled: true,
  basePrivateKey: '0x...',
  solanaPrivateKey: '...'
});

await server.start();

// Call tools
const result = await server.callTool('convert_media', {
  url: 'https://youtube.com/watch?v=...',
  format: 'mp3',
  network: 'base'
});

console.log(result);

📚 Additional Resources

• CNVRT Documentation: Main service documentation
• x402 Protocol: Payment protocol details
• MCP Specification: Model Context Protocol docs
• Claude MCP Guide: Claude-specific MCP setup

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md.

📄 License

MIT License - see LICENSE

💬 Support

• GitHub Issues: Report bugs
• Discord: Join the x402 community
• Email: [email protected]

Built with ❤️ for AI agents

Powered by x402 • Model Context Protocol • Coinbase CDP