{"_id":"@solvela/mcp-server","_rev":"2-77a0bb69e225bf69e6a02b413c11cd6f","name":"@solvela/mcp-server","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@solvela/mcp-server","version":"0.1.0","keywords":["mcp","solana","usdc","x402","llm","ai-agent"],"license":"Apache-2.0","_id":"@solvela/mcp-server@0.1.0","maintainers":[{"name":"white-bonnie","email":"solvela.ai@gmail.com"}],"homepage":"https://github.com/solvela-ai/solvela#readme","bugs":{"url":"https://github.com/solvela-ai/solvela/issues"},"bin":{"solvela-mcp":"dist/index.js"},"dist":{"shasum":"bce5f4b6d9a57b9d010a0519da28add1831e2cbc","tarball":"https://registry.npmjs.org/@solvela/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":38,"integrity":"sha512-/XJI/ZdhLzfq6m/IB0Dfc6sNcf9jLj1KAr913u19NHr5fMoCs79MNfRf58v3iB22rxFXzJSJP/rjeMHvy0ow5A==","signatures":[{"sig":"MEUCID9Kll5PshZtQ9r+2hDp5Bz5uOPHL8wnJYJX0M4lEPlvAiEA1w4ut5lKxRvWvl6hyVwBcT2/XuVIn4jwa/oCXjARdgA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@solvela%2fmcp-server@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":227994},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"ac3da6c01fd925cb106f1e88c9e0bf235d4b2a5c","scripts":{"dev":"tsc --watch","test":"node --test tests/server.test.ts tests/contract.test.ts tests/session.test.ts tests/escrow.test.ts tests/wallet.test.ts tests/ensure-gas.test.ts tests/search.test.ts","build":"tsc","start":"node dist/index.js","pretest":"node ../signer-core/scripts/ensure-built.mjs","prebuild":"node ../signer-core/scripts/ensure-built.mjs","prepublishOnly":"npm run build"},"_npmUser":{"name":"white-bonnie","email":"solvela.ai@gmail.com"},"overrides":{"uuid":"^11.1.1","ip-address":"^10.1.1"},"repository":{"url":"git+https://github.com/solvela-ai/solvela.git","type":"git","directory":"sdks/mcp"},"_npmVersion":"10.9.8","description":"MCP server for Solvela — AI agents pay for LLM calls with USDC on Solana","directories":{},"_nodeVersion":"22.23.0","dependencies":{"bs58":"^5.0.0","async-mutex":"^0.5.0","@solana/web3.js":"^1.87.0","@solana/spl-token":"^0.4.0","@solvela/signer-core":"^0.1.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.0_1782745711891_0.677495122461865","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@solvela/mcp-server","version":"0.1.1","description":"MCP server for Solvela — AI agents pay for LLM calls with USDC on Solana","type":"module","main":"dist/index.js","bin":{"solvela-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","test":"node --test tests/server.test.ts tests/contract.test.ts tests/session.test.ts tests/escrow.test.ts tests/wallet.test.ts tests/ensure-gas.test.ts tests/search.test.ts tests/price.test.ts","prebuild":"node ../signer-core/scripts/ensure-built.mjs","pretest":"node ../signer-core/scripts/ensure-built.mjs","prepublishOnly":"npm run build"},"keywords":["mcp","solana","usdc","x402","llm","ai-agent"],"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/solvela-ai/solvela.git","directory":"sdks/mcp"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","@solvela/signer-core":"^0.2.0","@solana/web3.js":"^1.87.0","@solana/spl-token":"^0.4.0","async-mutex":"^0.5.0","bs58":"^5.0.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"overrides":{"uuid":"^11.1.1","ip-address":"^10.1.1"},"_id":"@solvela/mcp-server@0.1.1","gitHead":"bf485c0f3b23a3888745beb40b0c800a5d2de10b","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/solvela-ai/solvela/issues"},"homepage":"https://github.com/solvela-ai/solvela#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-jw5XOrtRybrTqkPYkyOTQrk88Kl0BKETd8DtFQ6r5vNm5kVePekzof74LSQrzH9cIRbO1MVrXKISVKVEP+8Abg==","shasum":"97963b7151409d38704a7aa690cb803aad3fc476","tarball":"https://registry.npmjs.org/@solvela/mcp-server/-/mcp-server-0.1.1.tgz","fileCount":43,"unpackedSize":256741,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@solvela%2fmcp-server@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB8XR7Hf5IqqeEdjVcxopsvmxs0pdnz3Z6WYPjm8OfMbAiEAn+18RY1rmMpGgAUF1JEQ4e/UDKbnYA4TkuxqnUCOMCA="}]},"_npmUser":{"name":"white-bonnie","email":"solvela.ai@gmail.com"},"directories":{},"maintainers":[{"name":"white-bonnie","email":"solvela.ai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.1.1_1783521815913_0.537898317648299"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T15:08:31.756Z","modified":"2026-07-08T14:43:36.374Z","0.1.0":"2026-06-29T15:08:32.056Z","0.1.1":"2026-07-08T14:43:36.065Z"},"bugs":{"url":"https://github.com/solvela-ai/solvela/issues"},"license":"Apache-2.0","homepage":"https://github.com/solvela-ai/solvela#readme","keywords":["mcp","solana","usdc","x402","llm","ai-agent"],"repository":{"type":"git","url":"git+https://github.com/solvela-ai/solvela.git","directory":"sdks/mcp"},"description":"MCP server for Solvela — AI agents pay for LLM calls with USDC on Solana","maintainers":[{"name":"white-bonnie","email":"solvela.ai@gmail.com"}],"readme":"# @solvela/mcp-server\n\nMCP (Model Context Protocol) server for Solvela -- lets Claude Code, Claude Desktop, and any MCP-compatible host pay for LLM calls with USDC on Solana transparently.\n\nMCP is an open protocol that allows AI assistants to use external tools. This server exposes the Solvela gateway as a set of MCP tools: chat with any LLM model, use smart routing, search the web, check wallet status, list models, and track spending -- all with automatic x402 payment handling.\n\n## Quickstart\n\nInstall the `solvela` CLI, then run the one-line installer for your host:\n\n```bash\n# Install the Solvela CLI (once)\ncargo install solvela-cli\n\n# Install into your preferred host\nsolvela mcp install --host=claude-code\nsolvela mcp install --host=cursor\nsolvela mcp install --host=claude-desktop\nsolvela mcp install --host=openclaw\n```\n\nThe installer writes the correct config for your host. **You do not need to\ngenerate a keypair or set any wallet env var to get started** — on first run the\nserver resolves a non-custodial wallet automatically:\n\n1. If `SOLANA_WALLET_KEY` is set in the environment, that key is used (and no\n   file is read or created).\n2. Otherwise it reads `~/.solvela/wallet.json` if present (the same file the\n   `solvela` CLI uses — they share one wallet).\n3. If neither exists, it **generates a new ed25519 wallet and writes\n   `~/.solvela/wallet.json`** (mode `0600`, dir `0700`), then prints the new\n   address to stderr.\n\nAfter the first run, fund the printed address with **USDC-SPL on Solana** to\nstart paying for calls. You do **not** need any SOL — network gas is covered by\nthe gateway's gas-drip faucet, which sends a dust of SOL to USDC-funded wallets\nautomatically on startup.\n\n> **Back up `~/.solvela/wallet.json` — it controls your funds.** Anyone who can\n> read that file can drain the wallet. The private key never leaves your\n> machine; only signed transactions reach the gateway.\n\nTo use an existing keypair instead of the auto-created one, set it explicitly\n(it is intentionally never written to disk by the installer):\n\n```bash\nexport SOLANA_WALLET_KEY=<your-base58-keypair>\n```\n\nOptions:\n\n```\n--scope=user|project    user-scoped (default) or project-scoped config\n--wallet=<pubkey>       wallet address to embed (defaults to ~/.solvela/wallet.json)\n--budget=<usdc>         set SOLVELA_SESSION_BUDGET (e.g. \"2.00\")\n--signing-mode=auto     auto|escrow|direct|off\n--dry-run               print config without writing\n--diff                  show what would change vs the existing config\n--force                 overwrite an existing entry without prompting\n```\n\nTo remove:\n\n```bash\nsolvela mcp uninstall --host=claude-code\n```\n\nThe manual JSON snippets for each host are below as a fallback reference.\n\n## Installation\n\nThe package is published to npm, so the default path needs no manual build:\n`solvela mcp install` (Quickstart above) writes a host config that runs\n`npx -y @solvela/mcp-server`, fetching the latest version on demand. To run it\ndirectly:\n\n```bash\nnpx -y @solvela/mcp-server\n```\n\n**Building from source** (contributors, or to run an unreleased revision):\n\n```bash\ngit clone https://github.com/solvela-ai/solvela.git\ncd solvela/sdks/mcp\nnpm install\nnpm run build\n# Built artifact: dist/index.js — point a host config at its absolute path\nnode dist/index.js\n```\n\nThe manual JSON snippets below use the from-source absolute path\n(`\"command\": \"node\"`, `\"args\": [\"…/dist/index.js\"]`). For the published package,\nswap to `\"command\": \"npx\"`, `\"args\": [\"-y\", \"@solvela/mcp-server\"]` — or just run\n`solvela mcp install`, which writes the `npx` form for you.\n\n## Setup with Claude Code\n\nAdd to your Claude Code MCP configuration (`.claude/settings.json` or project-level):\n\n```json\n{\n  \"mcpServers\": {\n    \"solvela\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/solvela/sdks/mcp/dist/index.js\"],\n      \"env\": {\n        \"SOLVELA_API_URL\": \"http://localhost:8402\",\n        \"SOLVELA_SESSION_BUDGET\": \"1.00\",\n        \"SOLANA_WALLET_KEY\": \"YOUR_BASE58_SECRET_KEY\",\n        \"SOLANA_RPC_URL\": \"https://api.mainnet-beta.solana.com\",\n        \"SOLANA_WALLET_ADDRESS\": \"YOUR_WALLET_PUBKEY\"\n      }\n    }\n  }\n}\n```\n\n> **Security:** Never commit `SOLANA_WALLET_KEY` to version control. Store it in a\n> `.env` file with `0600` permissions or use your OS keychain. See [Security](#security).\n\n## Setup with Claude Desktop\n\nAdd to your Claude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"solvela\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/solvela/sdks/mcp/dist/index.js\"],\n      \"env\": {\n        \"SOLVELA_API_URL\": \"http://localhost:8402\",\n        \"SOLVELA_SESSION_BUDGET\": \"1.00\",\n        \"SOLANA_WALLET_KEY\": \"YOUR_BASE58_SECRET_KEY\",\n        \"SOLANA_RPC_URL\": \"https://api.mainnet-beta.solana.com\",\n        \"SOLANA_WALLET_ADDRESS\": \"YOUR_WALLET_PUBKEY\"\n      }\n    }\n  }\n}\n```\n\n> **Security:** Never commit `SOLANA_WALLET_KEY` to version control. Store it in a\n> `.env` file with `0600` permissions or use your OS keychain. See [Security](#security).\n\n## Setup with Cursor\n\nAdd to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"solvela\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/solvela/sdks/mcp/dist/index.js\"],\n      \"env\": {\n        \"SOLVELA_API_URL\": \"http://localhost:8402\",\n        \"SOLVELA_SESSION_BUDGET\": \"1.00\",\n        \"SOLANA_WALLET_KEY\": \"YOUR_BASE58_SECRET_KEY\",\n        \"SOLANA_RPC_URL\": \"https://api.mainnet-beta.solana.com\",\n        \"SOLANA_WALLET_ADDRESS\": \"YOUR_WALLET_PUBKEY\"\n      }\n    }\n  }\n}\n```\n\n> **Security:** Never commit `SOLANA_WALLET_KEY` to version control. Store it in a\n> `.env` file with `0600` permissions or use your OS keychain. See [Security](#security).\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SOLVELA_API_URL` | `https://api.solvela.ai` | Gateway URL |\n| `SOLVELA_SESSION_BUDGET` | unlimited | Max USDC to spend this session (e.g. `\"1.00\"`) |\n| `SOLVELA_TIMEOUT_MS` | `60000` | Request timeout in milliseconds |\n| `SOLVELA_SIGNING_MODE` | `auto` | Payment signing mode: `auto`, `escrow`, `direct`, or `off` |\n| `SOLVELA_ALLOW_DEV_BYPASS` | — | Set to `1` to silence the dev_bypass_payment gateway warning |\n| `SOLVELA_INSECURE_HTTP` | — | Set to `1` to silence the MITM warning when `SOLVELA_API_URL` is plaintext `http://`. Loopback and `*.local` hosts skip the warning unconditionally. |\n| `SOLVELA_ESCROW_MODE` | — | Set to `enabled` to expose the `deposit_escrow` tool |\n| `SOLVELA_MAX_ESCROW_DEPOSIT` | `5.0` | Per-call deposit cap in USDC (applies only when escrow mode is enabled) |\n| `SOLVELA_MAX_ESCROW_SESSION` | `20.0` | Cumulative session deposit cap in USDC (applies only when escrow mode is enabled) |\n| `SOLVELA_ESCROW_PROGRAM_ID` | required (when escrow enabled) | Base58 address of the Solvela escrow program on Solana |\n| `SOLVELA_RECIPIENT_WALLET` | required (when escrow enabled) | Base58 wallet address that receives escrow payments |\n| `SOLANA_WALLET_KEY` | auto-resolved | Base58-encoded Solana keypair secret key. **Optional** — when unset (and signing is enabled) the server reads or auto-creates `~/.solvela/wallet.json`. Set it to override the on-disk wallet. |\n| `SOLANA_RPC_URL` | required (when signing enabled) | Solana RPC endpoint (e.g. `https://api.mainnet-beta.solana.com`) |\n| `SOLANA_WALLET_ADDRESS` | derived from key | Display-only override. The address shown in `wallet_status` / `spending` is **derived from the resolved key**; if this env var is set and differs, the server logs a warning and uses the derived address. |\n\n### Escrow Mode\n\nSet `SOLVELA_ESCROW_MODE=enabled` to expose the `deposit_escrow` tool. This is intended for agent-driven workloads where the agent pre-funds an escrow PDA and the gateway claims only what was actually used.\n\n> ⚠️ **Enabling escrow mode authorizes any connected MCP host to spend real funds.** Once `SOLVELA_ESCROW_MODE=enabled` and a wallet key is configured, every MCP host connected to this server (Claude Code, automated agents, CI) can call `deposit_escrow` and broadcast real USDC transactions on Solana mainnet up to the per-call cap (`SOLVELA_MAX_ESCROW_DEPOSIT`, default $5) and session cap (`SOLVELA_MAX_ESCROW_SESSION`, default $20) — with **no further human confirmation from this server**. Any human-in-the-loop gate is the host's responsibility (e.g. tool-approval prompts). An autonomous agent can legitimately spend the entire session cap before any human reviews it. Only enable this mode with a wallet whose full session-cap loss is acceptable.\n\n**Do not enable escrow mode for interactive chat sessions** — the per-session deposit cap is a safeguard, not a substitute for careful budget management.\n\nWhen escrow mode is enabled, the server logs the effective caps at startup:\n\n```\n[solvela-mcp] escrow=enabled max-deposit=$5.00 max-session=$20.00\n```\n\nCaps are enforced in-process and persisted to `~/.solvela/mcp-session.json` so they survive restarts.\n\n### Session Persistence\n\nThe MCP server writes `~/.solvela/mcp-session.json` on every spend event. This file tracks:\n\n- `session_spent` — cumulative USDC spent via `chat` / `smart_chat`\n- `escrow_deposits_session` — cumulative USDC deposited via `deposit_escrow`\n- `request_count` — total requests this session\n- `last_updated` — ISO timestamp of last write\n\nExample file:\n\n```json\n{\n  \"session_spent\": 0.012500,\n  \"escrow_deposits_session\": 4.000000,\n  \"request_count\": 5,\n  \"last_updated\": \"2026-04-18T12:34:56.789Z\",\n  \"version\": 1\n}\n```\n\nThe file is written atomically (via a `.tmp` rename) with `0600` permissions on Unix. If the file is missing, corrupt, or has an unknown schema version, the server resets to zero and logs a `WARN` to stderr — it does not crash.\n\nTo reset the session counters and delete the file, call the `spending` tool with `reset: true`:\n\n```json\n{ \"tool\": \"spending\", \"arguments\": { \"reset\": true } }\n```\n\nOr delete the file manually:\n\n```bash\nrm ~/.solvela/mcp-session.json\n```\n\n**Security:** The session file never contains wallet keys or signing material. It is safe to inspect and delete at any time.\n\n### Signing Modes\n\n- **`auto`** (default) — The SDK prefers escrow deposits when the gateway advertises them, falling back to direct TransferChecked. Recommended for production.\n- **`escrow`** — Only use escrow payment schemes. Fails if the gateway does not advertise escrow.\n- **`direct`** — Only use direct USDC TransferChecked payment schemes. Ignores escrow offers.\n- **`off`** — Do not sign payments. Useful when the gateway runs with `dev_bypass_payment` enabled (development only). `SOLANA_WALLET_KEY` and `SOLANA_RPC_URL` are not required in this mode, and **no wallet file is read or created**.\n\nIn every mode except `off`, the wallet is resolved on startup using the\nprecedence `SOLANA_WALLET_KEY` env → `~/.solvela/wallet.json` → auto-create. The\ndisplayed wallet address is always derived from the resolved key.\n\n## Available Tools\n\nThe MCP server exposes seven tools (plus `deposit_escrow` when escrow mode is enabled):\n\n### `chat`\n\nSend a prompt to a specific LLM model through the gateway. Payment is handled automatically via USDC on Solana.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `model` | `string` | yes | Model identifier (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4`) |\n| `prompt` | `string` | yes | The user message |\n| `system` | `string` | no | System prompt to set assistant behaviour |\n| `max_tokens` | `number` | no | Maximum tokens in the response |\n| `temperature` | `number` | no | Sampling temperature (0.0--2.0) |\n\n### `smart_chat`\n\nSend a prompt using the gateway smart router. It automatically picks the cheapest capable model for the complexity of your request.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `prompt` | `string` | yes | The user message |\n| `profile` | `string` | no | Routing profile: `eco`, `auto` (default), `premium`, `free` |\n| `system` | `string` | no | System prompt |\n| `max_tokens` | `number` | no | Maximum tokens in the response |\n\n### `web_search`\n\nSearch the web through the gateway's x402-paid `POST /v1/search` endpoint. Payment is handled automatically: a flat per-call USDC price plus the standard 5% platform fee, settled on Solana. Always available (no escrow mode required). The result includes a cost line reporting the exact amount paid, e.g. `Paid 0.010500 USDC (0.010000 + 5% fee)` — derived from the 402 challenge's `cost_breakdown`, never a hardcoded value.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | `string` | yes | The search query (1--2000 characters) |\n| `max_results` | `number` | no | Maximum results to return (positive integer, clamped to 20) |\n\n### `solana_price`\n\nGet live USD prices for Solana tokens (SPL mints) through the gateway's x402-paid `POST /v1/solana/price` endpoint (Jupiter upstream). Payment is handled automatically: a flat per-call USDC price plus the standard 5% platform fee, settled on Solana. Always available (no escrow mode required). Mints the upstream has no reliable price for come back as explicit \"no reliable price\" rows, never an error for the whole batch — and the flat per-call price is charged regardless of how many mints resolve (an all-null response still costs the same, mirroring `web_search` with zero results). The result includes the same cost line as `web_search`, derived from the 402 challenge's `cost_breakdown`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `mints` | `string[]` | yes | Base58 SPL mint addresses to price (1--50 per call) |\n\n### `wallet_status`\n\nCheck the status of the configured Solana wallet and gateway connectivity. Returns the wallet address, gateway health, Solana RPC status, and current session spending.\n\nNo parameters.\n\n### `list_models`\n\nList all LLM models available through the gateway, including USDC pricing per million tokens.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `filter` | `string` | no | Substring filter (e.g. `gpt`, `claude`, `gemini`) |\n\n### `spending`\n\nShow USDC spending statistics for the current session: total spent, request count, remaining budget, and wallet address.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `reset` | `boolean` | no | If `true`, reset all session counters to zero and delete `~/.solvela/mcp-session.json` |\n\n### `deposit_escrow`\n\nDeposit USDC into a trustless escrow PDA on Solana for a future Solvela call. The gateway claims only what was actually used after the request completes; the remainder auto-refunds.\n\n**Only visible when `SOLVELA_ESCROW_MODE=enabled`.**\n\nRequires a signing wallet and `SOLANA_RPC_URL` regardless of `SOLVELA_SIGNING_MODE` (escrow always signs on-chain). The wallet is resolved the same way as for chat — `SOLANA_WALLET_KEY` env, then `~/.solvela/wallet.json`, auto-created if absent — even when `SOLVELA_SIGNING_MODE=off`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `amount_usdc` | `string` | yes | Amount to deposit in USDC (e.g. `\"2.50\"`) |\n| `max_timeout_seconds` | `number` | no | Escrow expiry in seconds (default: `300`) |\n\nReturns:\n\n```json\n{\n  \"deposit_tx_signature\": \"<base58 Solana tx signature>\",\n  \"escrow_pda\": \"<base58 PDA address>\",\n  \"amount_deposited_usdc\": \"2.500000\",\n  \"session_deposits_total_usdc\": \"6.500000\",\n  \"session_deposits_cap_usdc\": \"20.000000\"\n}\n```\n\n**Caps:**\n- Per-call: `SOLVELA_MAX_ESCROW_DEPOSIT` (default `$5.00`). Reject amounts above this threshold.\n- Session: `SOLVELA_MAX_ESCROW_SESSION` (default `$20.00`). Cumulative deposits this session, persisted across restarts.\n\nIf the on-chain deposit broadcast fails, the session cap is NOT incremented. The transaction is confirmed before returning (60 s timeout). If confirmation times out, the error message includes the transaction signature so you can check Solana Explorer.\n\n## Examples\n\nOnce the MCP server is configured, these tools are available to the AI assistant automatically. Here is how they work in practice:\n\n**Chat with a specific model:**\n\nThe assistant calls the `chat` tool with `model: \"openai/gpt-4o\"` and `prompt: \"Explain x402\"`. The MCP server sends the request to the gateway, handles the x402 payment flow, and returns the response along with token usage.\n\n**Use smart routing for cost optimization:**\n\nThe assistant calls `smart_chat` with `prompt: \"What is 2+2?\"` and `profile: \"eco\"`. The gateway analyzes prompt complexity and routes to the cheapest capable model.\n\n**Check wallet and gateway status:**\n\nThe assistant calls `wallet_status`. The server returns gateway connectivity, Solana RPC status, configured wallet address, and current session spend.\n\n**List available models:**\n\nThe assistant calls `list_models` with `filter: \"claude\"`. Returns all matching models with their per-million-token USDC pricing for input and output.\n\n**Monitor spending:**\n\nThe assistant calls `spending`. Returns total requests made, USDC spent this session, and remaining budget if one was configured.\n\n## Architecture\n\nThe MCP server depends on `@solvela/sdk` for real on-chain USDC payment signing. When a 402 Payment Required response is received from the gateway, the server:\n\n1. Parses the payment requirements (accepted schemes, amount, recipient)\n2. Applies the configured signing mode filter to the accepted schemes\n3. Calls `createPaymentHeader` from `@solvela/sdk` with the agent's private key\n4. Retries the request with the `payment-signature` header\n\nThe server communicates over stdio using the `@modelcontextprotocol/sdk` library. It:\n\n1. Accepts tool calls from the MCP host (Claude Code, Claude Desktop, etc.)\n2. Translates them into HTTP requests to the Solvela gateway\n3. Handles the x402 payment flow (402 -> sign -> retry)\n4. Tracks session spending and budget enforcement (concurrency-safe via mutex)\n5. Returns results as MCP tool responses\n\n## Security\n\n### Escrow mode — model-controlled money movement\n\nWhen `SOLVELA_ESCROW_MODE=enabled`, the `deposit_escrow` tool becomes\navailable to the AI model. The model decides when to deposit and how\nmuch (up to `SOLVELA_MAX_ESCROW_DEPOSIT` per call, `SOLVELA_MAX_ESCROW_SESSION`\nper session).\n\n**Threat model:** A prompt-injected or misaligned model could deposit\nup to the session cap without your explicit approval.\n\n**Mitigations:**\n- Caps are enforced both per-call and cumulatively per session.\n- The session cap is checked atomically (mutex-protected) so parallel tool\n  invocations cannot exceed the limit via a race condition.\n- Set caps conservatively (defaults: $5/call, $20/session).\n- The `spending` tool shows cumulative deposits at any time.\n- Run `spending` with `reset: true` to clear session counters.\n\n**WARNING on address trust:** `SOLVELA_RECIPIENT_WALLET` and\n`SOLVELA_ESCROW_PROGRAM_ID` control where your USDC is deposited.\nVerify these match the official Solvela addresses published at\nhttps://docs.solvela.ai/addresses before enabling. Both values are\nvalidated as valid Solana pubkeys at server startup — an invalid or\ntypo'd address causes an immediate fatal error rather than a silent\nmisdirected deposit. An attacker who can modify your MCP config file\ncan still redirect deposits to a different valid address.\n\n**Multi-process warning:** Session cap enforcement is in-process only.\nRunning two MCP server instances pointing at the same session file may\nallow the cumulative cap to be exceeded (no cross-process file lock).\nUse a single MCP server instance per session file.\n\n### Key storage model\n\nYour wallet's private key is a **hot-wallet secret**. Anyone who can read it can\ndrain your USDC. Treat it with the same care as an SSH private key.\n\n**Default (auto-wallet):** when `SOLANA_WALLET_KEY` is not set, the server stores\nthe key in `~/.solvela/wallet.json` (file mode `0600`, dir mode `0700`),\nauto-creating it on first run. This is the same file the `solvela` CLI uses, so\nthe CLI and the MCP server share one wallet. The file is written atomically and\nis **never overwritten** once it exists. On load it is validated (the key must\nbe exactly 64 bytes and its derived address must match the stored `address`); a\ncorrupt or tampered file is rejected rather than used. **Back up\n`~/.solvela/wallet.json` and keep it `0600`.**\n\n**The installer does NOT write `SOLANA_WALLET_KEY` to any config file by default.** The generated config intentionally omits the key. To use an explicit key instead of the auto-created file, supply it through one of the secure paths below.\n\n**`--include-key` flag (dev/CI only):** Passing this flag writes a plaintext placeholder into the config file. The installer emits a prominent stderr warning. Only use this in isolated dev environments or ephemeral CI runners where the config file is never committed or shared. The placeholder must be replaced with your actual key before the MCP server will work.\n\n### Recommended: store the key in `~/.solvela/env`\n\n```bash\nmkdir -p ~/.solvela\necho \"SOLANA_WALLET_KEY=<your-base58-private-key>\" > ~/.solvela/env\nchmod 0600 ~/.solvela/env\n```\n\n**Cursor users:** The installer writes `\"envFile\": \"${userHome}/.solvela/env\"` into the Cursor config by default (pass `--no-envfile` to disable). Cursor will source this file automatically, keeping the key out of the JSON config entirely. The file at `~/.solvela/env` should be `chmod 0600` and must never be committed to version control.\n\n**Claude Code / Claude Desktop / OpenClaw users:** Set the key in your shell profile:\n\n```bash\nexport SOLANA_WALLET_KEY=<your-base58-private-key>\n```\n\nOr store it in a `0600` file and source it from your profile.\n\n### General rules\n\n- Never commit `SOLANA_WALLET_KEY` or `~/.solvela/wallet.json` to version control. Add `*.env`, `.solvela/`, and any file containing the key to `.gitignore`.\n- The MCP server never logs, echoes, or returns the key in tool responses or startup notices (which print the **address only**). Stack traces and error messages are also sanitized.\n- The SDK zeroes secret key bytes in memory after signing.\n- Private key material flows only from the resolved wallet (env var or `~/.solvela/wallet.json`) into the signer — it is never passed through tool arguments (which are model-controlled).\n\n## Testing\n\n```bash\nnpm test\n```\n\nTests use Node.js built-in test runner with fetch mocking. No live gateway or Solana RPC required:\n\n```bash\nnode --test tests/server.test.ts\n```\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}