MCP Server

Overview

The Solvela MCP server exposes the gateway's capabilities as MCP tools, enabling MCP-compatible AI agents (like Claude Desktop) to call LLMs through Solvela's x402 payment infrastructure.

Installation

The MCP server is published to npm as @solvela/mcp-server@0.1.0. Install it globally, or run it on demand with npx:

npm install -g @solvela/mcp-server
# or, no install:
npx -y @solvela/mcp-server

Alternatively, build it from the monorepo:

git clone https://github.com/solvela-ai/solvela.git
cd solvela/sdks/mcp
npm install
npm run build
# Built artifact: dist/index.js

Run it directly to confirm the build:

node dist/index.js

Variable	Required	Description
`SOLANA_WALLET_KEY`	No	Base58-encoded Solana keypair secret. When unset, the server loads `~/.solvela/wallet.json`, auto-creating a new wallet on first run. Set this to use a specific keypair instead.
`SOLANA_RPC_URL`	Yes, unless `SOLVELA_SIGNING_MODE=off`	Solana JSON-RPC endpoint. With signing enabled (the default) the server exits at startup if this is unset — set `SOLVELA_SIGNING_MODE=off` to run signing-free (e.g. just `list_models`).
`SOLVELA_API_URL`	No	Gateway base URL (default `https://api.solvela.ai`)
`SOLVELA_SESSION_BUDGET`	No	Per-session USDC cap (e.g. `2.00`)
`SOLVELA_TIMEOUT_MS`	No	HTTP timeout for gateway calls
`SOLVELA_SIGNING_MODE`	No	`auto` / `escrow` / `direct` / `off` (default `auto`)
`SOLVELA_ESCROW_MODE`	No	Set to `enabled` to expose the `deposit_escrow` tool
`SOLVELA_ESCROW_PROGRAM_ID`	If `SOLVELA_ESCROW_MODE=enabled`	Escrow program ID on Solana mainnet
`SOLVELA_RECIPIENT_WALLET`	If `SOLVELA_ESCROW_MODE=enabled`	Gateway recipient pubkey

SOLANA_WALLET_KEY is the full Solana keypair secret. Treat it like any other production credential — never commit it to source, and prefer a secrets manager or your host's encrypted env-var store over a plaintext shell profile.

Claude Desktop integration

Add an entry to claude_desktop_config.json that runs the published package via npx:

{
  "mcpServers": {
    "solvela": {
      "command": "npx",
      "args": ["-y", "@solvela/mcp-server"],
      "env": {
        "SOLVELA_API_URL": "https://api.solvela.ai",
        "SOLANA_WALLET_KEY": "<base58-keypair-secret>",
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
      }
    }
  }
}

If you built from source instead, point command at node and args at the absolute path to your locally-built dist/index.js:

{
  "mcpServers": {
    "solvela": {
      "command": "node",
      "args": ["/absolute/path/to/solvela/sdks/mcp/dist/index.js"],
      "env": {
        "SOLVELA_API_URL": "https://api.solvela.ai",
        "SOLANA_WALLET_KEY": "<base58-keypair-secret>",
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
      }
    }
  }
}

Available tools

The MCP server exposes the following tools to connected agents:

Tool	Description
`chat`	Send a prompt to a specific LLM model
`smart_chat`	Send a prompt via the smart router — it auto-selects the model
`web_search`	Search the web and get titled, linked result snippets (always available; no escrow mode required)
`wallet_status`	Check the configured Solana wallet's status and gateway connectivity
`list_models`	List available models with pricing
`spending`	Show USDC spending statistics for the current session
`deposit_escrow`	Deposit USDC into a trustless escrow PDA for a future call (only listed when `SOLVELA_ESCROW_MODE=enabled`)

Example usage in Claude Desktop

Once configured, Claude can call the Solvela gateway directly:

User: Use Solvela to ask GPT-4o what the capital of France is.
Claude: [calls solvela.chat with model="openai/gpt-4o"]

Warning

The MCP server performs real Solana USDC-SPL signing via @solvela/signer-core when SOLANA_WALLET_KEY is set. If signing degrades to stub mode (for example, when @solana/web3.js peer dependencies cannot be resolved), the server rejects the call rather than sending a placeholder signature — a misconfigured build fails loudly instead of burning budget.

Note

Source code: sdks/mcp/ in the monorepo.

Overview

Installation

Configuration

Claude Desktop integration

Available tools

Example usage in Claude Desktop