Skip to main content

MCP Server Access

Let your AI assistant use Bitcoin-powered AI tools

Give Your AI Superpowers

Connect Claude, Cursor, or any MCP-compatible AI to 23+ tools — images, video, music, text, speech, and more.

No signupNo subscriptionPay only when you use itFull privacy

Not a developer? You can use all of these tools directly on the web — browse available tools and pay with any Lightning wallet, no setup needed.

Connect in 30 Seconds

Copy this into your MCP settings and you're done.

Add to your MCP settings JSON:
{
  "mcpServers": {
    "sats4ai": {
      "url": "https://sats4ai.com/api/mcp"
    }
  }
}
Claude Desktop: claude_desktop_config.json
Claude Code: .claude/settings.json
Cursor: .cursor/mcp.json

Also on the Official MCP Registry as com.sats4ai/bitcoin-ai-tools.

How Payments Work

Your AI handles steps 1, 3, and 4 automatically. You just pay the invoice.

1

Create Payment

AI calls create_payment and gets a Lightning invoice

You Pay

Pay the Lightning invoice with your wallet. Agents: CLW

3

Verify (optional)

AI checks payment status

4

Get Result

AI calls the tool and returns your result

Available Services & Pricing

All prices in Satoshis. Model ID is optional — omit it to use the best default. Use list_models to discover all options.

IDServicePrice (Satoshis)
1text (Standard)333 characters/Sat, min 5
6text (Best)100 characters/Sat, min 15
2image100
8image150
16image200
25video300-550/sec
24video_from_image100/sec
23music100
3tts300
10transcription10/minute
5vision21
173d350
27ocr10/page
file_convert100
20smsvaries
callvaries
email200
translatefrom 4
image_edit200-450
voice_clone7,500
html_to_pdf50
pdf_merge100
receipt_ocr50

Text and SMS use dynamic pricing. Call create_payment to get an exact quote. Free tools: list_models, get_model_pricing.

Model IDs are stable numeric database keys — they never change. The table above is for human reference. Agents should call list_models at runtime to discover current IDs and pick up new models automatically.

Media URLs returned by image, video, audio, and file conversion tools are hosted on our servers and expire after 2 hours. Download or display them promptly.

Step-by-Step: Manual Usage

If your AI client doesn't auto-handle MCP, or you want to call it directly with curl:

1Initialize Connection

curl -X POST https://sats4ai.com/api/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  }
}'

2Create Payment (get Lightning invoice)

curl -X POST https://sats4ai.com/api/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_payment",
    "arguments": {
      "toolName": "image"
    }
  }
}'

Response:

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{
        \"paymentId\": \"abc123\",
        \"lightningInvoice\": \"lnbc...<LIGHTNING_INVOICE>\",
        \"amountSats\": 100
      }"
    }]
  }
}

Copy the lightningInvoice and pay it with your Lightning wallet. Save the paymentId.

3Call the Service

After payment, pass the paymentId to the tool you want to use:

curl -X POST https://sats4ai.com/api/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "image",
    "arguments": {
      "paymentId": "abc123",
      "prompt": "A futuristic Bitcoin-powered robot"
    }
  }
}'

All Available Tools

Free Tools (no payment needed)

create_payment

Get a Lightning invoice for any service

check_payment_status

Check if your payment was received

list_models

List all available AI models

get_model_pricing

Get pricing for a specific model

check_job_status

Check progress of async jobs

get_job_result

Get result of completed jobs

Paid Tools (instant result)

image

Generate images from text. Returns image URL. modelId optional (defaults to best).

text

AI chat, code review, file analysis. Returns generated text. modelId optional.

music

Create music from text prompts. Returns audio URL. modelId optional.

tts

Text to speech. Returns audio URL. modelId optional.

vision

Analyze images with AI. Returns description text. modelId optional.

ocr

Extract text from PDFs and images. Returns Markdown. modelId optional.

sms

Send SMS messages globally. Returns delivery status.

call

Phone calls with TTS or audio playback. Returns call status.

file_convert

Convert between file formats. Returns converted file URL.

email

Send emails to any address. No domain setup needed. 200 sats.

image_edit

Edit images with AI — background removal, style transfer, object removal. 200-450 sats (1K/2K/4K).

pdf_merge

Merge multiple PDFs into one document. 100 sats.

html_to_pdf

Convert HTML or Markdown to PDF. Great for invoices/reports. 50 sats.

translate

Translate text across 119 languages. From 4 sats.

receipt_ocr

Extract structured JSON from receipts and invoices. 50 sats.

Paid Tools (async — requires polling)

videoasync

Generate videos from text. Returns requestId, then poll for video URL. modelId optional.

video_from_imageasync

Animate images into video. Returns requestId. modelId optional.

3dasync

Generate 3D models from images. Returns requestId, then poll for model URL. modelId optional.

voice_cloneasync

Clone a voice from audio sample. Returns voice_id for TTS. 7,500 sats. Takes 1-5 minutes.

transcriptionasync

Audio to text with speaker diarization and timestamps. Returns requestId, poll for transcript.

Async tools return a requestId. Use check_job_status to poll, then get_job_result to retrieve the output.

Tool Reference

Copy-paste JSON for each tool. These go inside params.arguments.

create_payment — get a Lightning invoice

For most services (image, video, music, etc.). modelId is optional — omit to use the best default:

{
  "toolName": "image"       // Tool to pay for. modelId optional (defaults to best).
}

With a specific model (optional):

{
  "toolName": "image",
  "modelId": 8              // Optional: pick a specific model from list_models
}

For text (prompt required — price is based on character count and locked to the exact prompt):

{
  "toolName": "text",
  "prompt": "Review this code for bugs",         // Required: used to calculate and lock the price
  "modelId": 6,                                  // Optional: 1 = Standard, 6 = Best (default)
  "systemPrompt": "You are a helpful assistant", // Optional
  "fileContext": "function add(a, b) { ... }"    // Optional: extracted file text
}

For video (duration/mode/audio determine price):

{
  "toolName": "video",
  "duration": 5,               // 3-15 seconds (required)
  "mode": "pro",               // "standard" or "pro" (default: "pro")
  "generate_audio": false      // Include audio track (default: false)
}
// Pricing: standard 300/400 sats/sec, pro 450/550 sats/sec (no audio/audio)
// video_from_image: just provide "duration" (100 sats/sec)

For SMS (destination-aware pricing):

{
  "toolName": "sms",
  "phoneNumber": "+14155550100",    // Required: used for rate lookup
  "message": "Hello from Sats4AI!" // Required: validated here (max 120 chars)
}
image — generate images from text. Returns image URL.
{
  "paymentId": "abc123",
  "prompt": "A futuristic city at sunset",
  "modelId": 2,                          // Optional: defaults to best
  "imageBase64": "..."                   // Optional: base64 image for img2img
}
text — AI chat, code review, file analysis. Returns generated text.

Supports file attachments (send extracted text as fileContext) and image analysis (send base64 as imageBase64).

{
  "paymentId": "abc123",
  "prompt": "Review this code for bugs",
  "modelId": 6,                                  // Optional: defaults to best
  "systemPrompt": "You are a helpful assistant",  // Optional
  "fileContext": "function add(a, b) { ... }",   // Optional: extracted file text
  "fileName": "utils.js",                         // Optional: file name
  "imageBase64": "data:image/png;base64,..."      // Optional: vision-capable models only
}
video — text to video. Returns requestId, poll for video URL. async
{
  "paymentId": "abc123",
  "prompt": "A rocket launching into space",
  "modelId": 25,           // Optional: defaults to best
  "duration": 5,           // 3-15 seconds
  "mode": "pro",           // "standard" or "pro"
  "generate_audio": false  // Include audio track
}
// Pricing (per second): standard 300 (no audio) / 400 (audio), pro 450 / 550
// Must provide duration, mode, generate_audio at create_payment time
video_from_image — animate an image into video. Returns requestId. async
{
  "paymentId": "abc123",
  "imageBase64": "<base64 encoded image>",
  "prompt": "The scene comes to life",    // Optional motion guidance
  "modelId": 24,                           // Optional: defaults to best
  "duration": 5                            // 3-15 seconds, 100 sats/sec
}
// Must provide duration at create_payment time
music — create music from text. Returns audio URL.
{
  "paymentId": "abc123",
  "prompt": "Upbeat electronic music with a driving beat",
  "modelId": 23,         // Optional: defaults to best
  "duration": 30,        // Duration in seconds (optional)
  "referenceAudio": ""   // Optional: URL to reference audio
}
tts — text to speech. Returns audio URL.
{
  "paymentId": "abc123",
  "text": "Hello, this is a test of the speech synthesis.",
  "modelId": 3,       // Optional: defaults to best
  "voice": "default"  // Optional: voice ID
}
transcription — audio to text with diarization and timestamps. Returns requestId, poll for result. async
{
  "paymentId": "abc123",
  "audioBase64": "<base64-encoded-audio>",  // mp3, wav, flac, ogg, webm, mp4, m4a, aac, wma
  "language": "en",              // Optional: "detect", "en", "es", "fr", "de", "it", "pt", "nl", "ja", "ko", "zh", "ar", "hi"
  "timestamps": "segment",      // Optional: "none" (default), "segment", or "word"
  "diarize": true                // Optional: identify different speakers (default: false)
}

Returns requestId. Poll with check_job_status(jobType="transcription"), then get_job_result. 10 sats/minute.

vision — analyze images with AI. Returns description text.
{
  "paymentId": "abc123",
  "imageUrl": "https://example.com/image.jpg",
  "prompt": "What objects are in this image?",
  "modelId": 5    // Optional: defaults to best
}
3d — image to 3D model. Returns requestId, poll for model URL. async
{
  "paymentId": "abc123",
  "imageUrl": "https://example.com/object.jpg",
  "modelId": 17    // Optional: defaults to best
}
sms — send text messages globally. Returns delivery status.
{
  "paymentId": "abc123",
  "phoneNumber": "+14155550100",    // Same as in create_payment
  "message": "Hello from Sats4AI!" // Max 120 chars
}

A 40-character disclaimer is auto-appended to every SMS.

call — phone calls with TTS or audio playback. Returns call status.
// Option A: Text-to-Speech
{
  "paymentId": "abc123",
  "phoneNumber": "+14155550100",
  "message": "Hello, this is your reminder for tomorrow at 3 PM."
}

// Option B: Play audio file
{
  "paymentId": "abc123",
  "phoneNumber": "+14155550100",
  "audioUrl": "https://example.com/my-audio.mp3",
  "durationMinutes": 2
}

Provide message (max 500 chars) OR audioUrl + durationMinutes (1–30). Pricing scales with duration and destination. Generate audio with tts first for custom voices.

ocr — extract text from PDFs and images. Returns Markdown.
{
  "paymentId": "abc123",
  "document": "data:application/pdf;base64,...",  // PDF or image as data URI
  "model": "OCR"
}

Returns Markdown with tables, headers, and formatting preserved. 10 Sats/page.

file_convert — convert between file formats. Returns converted file URL.
{
  "paymentId": "abc123",
  "fileBase64": "...",            // Base64-encoded file
  "fileName": "document.docx",
  "extensionFrom": "docx",
  "extensionTo": "pdf"
}
list_models / get_model_pricing — free lookup tools
// list_models — filter by type (optional)
{
  "type": "Image"  // Image, Conversation, Video, etc.
}

// get_model_pricing — look up a specific model
{
  "modelId": 2
}
check_job_status / get_job_result — async job helpers
// check_job_status
{
  "requestId": "xyz789",
  "jobType": "video"      // "video", "video-image", "image-3d", or "transcription"
}

// get_job_result
{
  "requestId": "xyz789",
  "jobType": "video"      // same job types as above
}

Async Operations (Video, 3D, Voice Clone, Transcription)

Video, video-from-image, 3D generation, voice cloning, and transcription take time. They return a requestId immediately — poll until complete:

// Step 1: Generate video (returns requestId)
const videoJob = await mcpRequest('tools/call', {
  name: 'video',
  arguments: {
    paymentId: 'abc123',
    prompt: 'A rocket launching into space',
    duration: 5,
    mode: 'pro',
    generate_audio: false
  }
});
// Returns: { requestId: 'xyz789', status: 'IN_PROGRESS' }

// Step 2: Poll status until complete
let status;
do {
  await sleep(5000);
  status = await mcpRequest('tools/call', {
    name: 'check_job_status',
    arguments: { requestId: 'xyz789', jobType: 'video' }
  });
} while (status.status === 'IN_PROGRESS');

// Step 3: Get the result
const result = await mcpRequest('tools/call', {
  name: 'get_job_result',
  arguments: { requestId: 'xyz789', jobType: 'video' }
});
// Returns: { videoUrl: 'https://...' }

Error Handling

Errors come back in standard JSON-RPC format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Payment has not been received yet"
  }
}
CodeMeaning
-32700Invalid JSON
-32600Missing required fields
-32601Method not found
-32602Wrong parameter types
-32603Internal error (service failure or unpaid invoice)

MCP Resources

MCP clients can also read these resources directly:

URIDescription
sats4ai://modelsAll AI models with specs and pricing
sats4ai://pricingPricing for all services
/api/models/routingModel routing transparency — which models power each service, tiers, defaults, and resolution strategy

OpenClaw Integration

OpenClaw agents can use Sats4AI tools directly:

Option 1: MCP Skill (Recommended)

// Add to openclaw.json
{
  "mcpServers": {
    "sats4ai": { "url": "https://sats4ai.com/api/mcp" }
  }
}

Option 2: L402 with lnget

# Agent pays automatically — no API key needed
lnget -X POST https://sats4ai.com/api/l402/generate-image \
  -d '{"input":{"prompt":"A Viking visiting Constantinople"},"model":"Best"}'

Service Discovery

curl https://sats4ai.com/.well-known/mcp          # MCP manifest
curl https://sats4ai.com/.well-known/l402-services  # L402 catalog + pricing
curl https://sats4ai.com/api/models/routing        # Model routing transparency

What is MCP?

MCP (Model Context Protocol) is an open standard by Anthropic that lets AI assistants connect to external tools and services. Think of it as a universal plug — any AI that supports MCP can use any MCP-compatible service.

Sats4AI's MCP server adds Bitcoin Lightning payments on top. Your AI assistant can generate images, write text, create videos, and more — paying per use with Sats instead of monthly subscriptions. No account needed, no personal data collected, no recurring charges. You only pay when you actually use a tool.

Learn more about MCP

Need Help?

Questions or issues? Visit our contact page or check the official MCP docs.