Stellar Protocol 22 Active|Institutional MCP Tooling System

The Model Context Protocol for Stellar

Connect autonomous AI agents to decentralized financial rails. Monetize MCP tools with HTTP 402 micro-payment challenges settled via Native XLM, Soroban SAC tokens, DEX Path Payments, and State Channels.

Read Documentation →GitHub Repository Testnet Contract ↗

$pnpm add @stellar-mcp/agent-client @stellar-mcp/server

17+ Tools

Horizon & Soroban RPC

Account state, DEX orderbooks, AMM liquidity pools, transaction simulation, and storage deserialization.

7 Rails

Stellar Payment Modalities

Native XLM, Soroban SAC USDC, Path Payments, Claimable Balances, Fee-Bumps, State Channels, and AMM Swaps.

5,908 B

Soroban State Channels

Optimized WASM bytecode deployed on Testnet, achieving 99.8% fee savings and zero gas for off-chain micro-vouchers.

250 Codes

Universal Error Taxonomy

Machine-actionable error registry across 7 domains with deterministic remedies for autonomous agents.

Interactive Sandbox

Developer Integration & Execution Sandbox

Zero glue-code adapters for leading AI agent frameworks with automated HTTP 402 payment settlement.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { createVercelAITools } from '@stellar-mcp/adapters/vercel';
import { X402AgentMcpClient } from '@stellar-mcp/agent-client';
 
// 1. Initialize client with Ed25519 signer & spending guardrails
const client = new X402AgentMcpClient({
  network: 'testnet',
  secretKey: process.env.STELLAR_AGENT_SECRET,
  maxDailyBudgetXlm: '50.0',
});
 
// 2. Wrap MCP tools with automated x402 payment resolution
const tools = createVercelAITools(mcpTools, client);
 
// 3. Execute autonomous agent reasoning loop
const { text } = await generateText({
  model: openai('gpt-4o'),
  tools,
  prompt: 'Query real-time DEX liquidity for XLM/USDC and simulate contract CDAVUN...',
});

Interactive MCP Tool Runner

Execute Horizon and Soroban RPC tools against live Stellar Testnet protocols.

SELECT MCP TOOL

Queries native XLM and SAC token balances for any Stellar address.

TOOL ARGUMENTS (JSON)

EXECUTION RESPONSE

// Click "Run" to dispatch MCP tool to Stellar Testnet...

Interactive x402 Payment Simulator

Observe autonomous HTTP 402 challenge negotiation, Ed25519 signing, and on-chain receipt verification.

STEP 01ACTIVE

1. Agent Dispatches Tool Call

Autonomous agent attempts invoking paywalled tool without payment headers.

{
  "method": "tools/call",
  "params": {
    "name": "stellar_get_orderbook",
    "arguments": {
      "selling": "native",
      "buying": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
    }
  }
}

STEP 02PENDING

2. HTTP 402 Challenge Emitted

Paywall interceptor traps request, generates SEP-0043 challenge, and returns HTTP 402 with code 1120.

{
  "status": 402,
  "error": "ERR_PAYWALL_PAYMENT_REQUIRED",
  "code": 1120,
  "headers": {
    "X-Payment-Challenge": "0a9f8b...7c2d",
    "X-Payment-Amount": "0.0050000",
    "X-Payment-Asset": "native",
    "X-Payment-Recipient": "GCQURZFYPPAN76FRARROTSTYVH2LQ5AP7OLDXMJPIQ7STDOM55FXWD4T"
  }
}

STEP 03PENDING

3. Wallet Signer Resolves Challenge

Client-side InMemoryWalletSigner checks budget policy and signs payment envelope on Stellar Testnet.

{
  "payer": "GDKF5...92KA",
  "method": "native_xlm",
  "amount": "0.0050000",
  "txHash": "55324f4c7277b8596452723f894fce3061a019e7cf98d080f2dfea65f5144935",
  "signature": "1ee32c4573de233b83c7aca088345c3dba3c80fd0b1957e38a1ca0790032d8a4..."
}

STEP 04PENDING

4. Verifier and Replay Protection Check

OnChainTransactionVerifier confirms ledger finality. ReplayProtector claims nonce in LRU cache with TTL.

{
  "verified": true,
  "network": "stellar:testnet",
  "ledgerClosed": 1048291,
  "replayCheck": "CLAIMED_NEW_NONCE",
  "feePaid": "100 stroops"
}

STEP 05PENDING

5. Tool Executes and Yields Data

Tool handler executes with authenticated payment context and returns requested Stellar market data.

{
  "result": {
    "bidsCount": 14,
    "asksCount": 22,
    "midPrice": "0.1245000",
    "spreadBps": 18.2,
    "settledVia": "x402-v1"
  }
}

Soroban State Channel Gas Optimization and Benchmarks

Micro-payment state channel smart contract deployed to Stellar Testnet, optimized for ultra-low gas consumption.

Deployed Contract (Testnet)

Optimized Size: 5,908 Bytes

Contract Address:

CDAVUNF5DHX2MWF33XDMY7WKVBSQZ3SXZDT2TPSNZPEB3Z4HHPPKTVGY

WASM Bytecode SHA-256 Hash:

dcf795a2daff9472f0796ca0188e4f5cae0c868a68cd70dc755557708b4efdb3

View on Stellar.expert Explorer →Interact in Stellar Laboratory →

open_channel()

CPU Cost:289,245

Memory:112,575 B

Network Fee:200 stroops

Locks SAC tokens in escrow and initializes monotonic sequence state

claim_payment()

CPU Cost:320,109

Memory:120,025 B

Network Fee:250 stroops

Merchant settles cumulative off-chain vouchers with monotonic delta payout

close_channel()

CPU Cost:322,217

Memory:115,317 B

Network Fee:220 stroops

Cooperative close returning unspent balance to payer

off-chain voucher()

CPU Cost:0

Memory:0 B

Network Fee:0 stroops

Ed25519 signed state update exchange between agent and server

Machine-Readable Diagnostics

Universal 250 Error Codes Registry

Exhaustive machine-readable error classification across all 7 protocol domains with deterministic remedies.

View Full Directory on GitBook →

Featured Common Error Codes

#1120PAYWALL

Permanent

ERR_PAYWALL_PAYMENT_REQUIRED

Request requires payment header (HTTP 402 Payment Required)

Remedy: Inspect X-Payment-Challenge header, settle payment on Stellar, and retry with signature

#1160REPLAY

Permanent

ERR_REPLAY_TX_HASH_CLAIMED

Transaction hash already exists in claimed nonces registry

Remedy: Every tool invocation requires a fresh, unspent transaction

#1190CLIENT

Permanent

ERR_CLIENT_BUDGET_CALL_EXCEEDED

Invocation cost exceeds maxSpendPerCall limit

Remedy: Increase maxSpendPerCall budget policy on agent client

Developer & Institutional Resources

Verified deployments, technical documentation, and open-source repositories.

Official Documentation Portal →26 guides on GitBook covering architecture, payments, SDKs, and error codes GitHub Monorepo →Complete TypeScript monorepo, contracts, and multi-node CI workflows Testnet Contract Explorer →Verified on-chain contract CDAVUN... on Stellar Expert Stellar Laboratory →Direct Soroban RPC contract inspection and live invocation harness