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.
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.
{
"mcpServers": {
"sats4ai": {
"url": "https://sats4ai.com/api/mcp"
}
}
}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.
Create Payment
AI calls create_payment and gets a Lightning invoice
You Pay
Pay the Lightning invoice with your wallet. Agents: CLW
Verify (optional)
AI checks payment status
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.
| ID | Service | Price (Satoshis) |
|---|---|---|
| 1 | text (Standard) | 333 characters/Sat, min 5 |
| 6 | text (Best) | 100 characters/Sat, min 15 |
| 2 | image | 100 |
| 8 | image | 150 |
| 16 | image | 200 |
| 25 | video | 300-550/sec |
| 24 | video_from_image | 100/sec |
| 23 | music | 100 |
| 3 | tts | 300 |
| 10 | transcription | 10/minute |
| 5 | vision | 21 |
| 17 | 3d | 350 |
| 27 | ocr | 10/page |
| — | file_convert | 100 |
| 20 | sms | varies |
| — | call | varies |
| — | email | 200 |
| — | translate | from 4 |
| — | image_edit | 200-450 |
| — | voice_clone | 7,500 |
| — | html_to_pdf | 50 |
| — | pdf_merge | 100 |
| — | receipt_ocr | 50 |
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_paymentGet a Lightning invoice for any service
check_payment_statusCheck if your payment was received
list_modelsList all available AI models
get_model_pricingGet pricing for a specific model
check_job_statusCheck progress of async jobs
get_job_resultGet result of completed jobs
Paid Tools (instant result)
imageGenerate images from text. Returns image URL. modelId optional (defaults to best).
textAI chat, code review, file analysis. Returns generated text. modelId optional.
musicCreate music from text prompts. Returns audio URL. modelId optional.
ttsText to speech. Returns audio URL. modelId optional.
visionAnalyze images with AI. Returns description text. modelId optional.
ocrExtract text from PDFs and images. Returns Markdown. modelId optional.
smsSend SMS messages globally. Returns delivery status.
callPhone calls with TTS or audio playback. Returns call status.
file_convertConvert between file formats. Returns converted file URL.
emailSend emails to any address. No domain setup needed. 200 sats.
image_editEdit images with AI — background removal, style transfer, object removal. 200-450 sats (1K/2K/4K).
pdf_mergeMerge multiple PDFs into one document. 100 sats.
html_to_pdfConvert HTML or Markdown to PDF. Great for invoices/reports. 50 sats.
translateTranslate text across 119 languages. From 4 sats.
receipt_ocrExtract structured JSON from receipts and invoices. 50 sats.
Paid Tools (async — requires polling)
videoasyncGenerate videos from text. Returns requestId, then poll for video URL. modelId optional.
video_from_imageasyncAnimate images into video. Returns requestId. modelId optional.
3dasyncGenerate 3D models from images. Returns requestId, then poll for model URL. modelId optional.
voice_cloneasyncClone a voice from audio sample. Returns voice_id for TTS. 7,500 sats. Takes 1-5 minutes.
transcriptionasyncAudio 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 timevideo_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 timemusic — 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"
}
}| Code | Meaning |
|---|---|
-32700 | Invalid JSON |
-32600 | Missing required fields |
-32601 | Method not found |
-32602 | Wrong parameter types |
-32603 | Internal error (service failure or unpaid invoice) |
MCP Resources
MCP clients can also read these resources directly:
| URI | Description |
|---|---|
sats4ai://models | All AI models with specs and pricing |
sats4ai://pricing | Pricing for all services |
/api/models/routing | Model 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 transparencyWhat 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.
Need Help?
Questions or issues? Visit our contact page or check the official MCP docs.