# Connect your AI client Connect your favorite AI coding agent to svpchain and let it place orders, move funds, and read live chain state — all in natural language. svpchain ships two MCP servers you can drop into Claude, Cursor, Windsurf, and any other [MCP](https://modelcontextprotocol.io/)-aware client: * **`svpchain-remote`** — a chain front-end that builds, reads, and broadcasts. Hosted by you (or your team) on a server with network access to a svpchain node and indexer. * **`svpchain-signer`** — a local-only signer that holds your key and signs transactions the remote server builds. Runs on your machine; the key never leaves it. Your agent composes the two: it asks the remote to build a transaction, asks the local signer to sign it, then asks the remote to broadcast. Authentication is self-service — your agent proves it controls a key by signing a one-time challenge, no operator pre-provisioning needed. ## Choose your setup path | Your machine | Recommended path | | ----------------------------------- | --------------------------------------------------------------------------------------------------------- | | **macOS** | [GUI app (macOS)](#macos-gui-app) — download, open the app, follow on-screen steps. No terminal required. | | **Linux, WSL, Intel Mac, headless** | [CLI setup](#cli-setup) — download the binary, import your key, paste MCP config manually. | > **Use a dedicated trading wallet.** Whatever key the signer holds is fully exposed to the agent — anything the agent can authorize (trades, deposits, withdraws within the limits below) will execute. Don't use a wallet that holds funds you wouldn't want an agent to touch. ## macOS (GUI app) On macOS you can skip the [CLI setup](#cli-setup) sections entirely — no binary install, no `import` command, no manual JSON editing unless the app asks you to paste something into your client. 1. Open the [svpchain-signer-mcp releases page](https://github.com/svpchain/svpchain-signer-mcp/releases/) and download the latest **`svpchain-signer-*-macos.zip`** (macOS app bundle — contains **`svpchain signer.app`** and a short README). 2. Unzip the download and open **`svpchain signer.app`**. If macOS blocks it the first time ("developer cannot be verified"), follow the instructions in **`READ-BEFORE-RUN.txt`** / **`运行前先阅读.txt`** inside the zip. 3. In the app, follow the on-screen flow: * Import your private key (same 32-byte hex MetaMask key described in [CLI setup → Prerequisites](#cli-setup) if you need help exporting it). * Pick the chain id your remote uses (`svp-2517-1` for the public indexer below). * Copy the **MCP JSON** the app generates into your AI client (Cursor, Claude Desktop, …) — the app writes the correct `command` path and `--chain-id` for you. 4. Add the **`svpchain-remote`** entry if the app doesn't include it already: ```json "svpchain-remote": { "type": "http", "url": "https://indexer.svpchain.com/mcp" } ``` 5. Restart your client and jump to [Verify the connection](#verify-the-connection). The release page also ships **`svpchain-signer-gui`** (graphical setup without the `.app` bundle) and **`svpchain-signer-mcp`** (CLI binary) if you prefer those instead — but the `.app` zip is the simplest path on Mac. Verify downloads against **`SHA256SUMS`** on the release page before opening anything that will hold your key: ```bash shasum -a 256 -c SHA256SUMS ``` > Download signer binaries **only** from the [official releases page](https://github.com/svpchain/svpchain-signer-mcp/releases/). These tools hold your signing key locally. ## CLI setup Follow this section on **Linux**, **WSL**, **Intel Mac** (no Apple Silicon build), or any **headless** host. macOS users who prefer the GUI should use [macOS (GUI app)](#macos-gui-app) instead. ### Prerequisites You will need: * **A 32-byte hex private key.** svpchain uses `eth_secp256k1`, the same curve as Ethereum — your MetaMask key works directly. In MetaMask: open the account menu → **Account details** → **Show private key** → enter your password → copy the value. It's a 64-char hex string, optionally prefixed with `0x` (the signer tolerates both). You'll load it into your OS credential store in the **Import your key** step below — don't paste it into chats, commit it, or share it. > macOS users: import the key through **`svpchain signer.app`** instead — see [macOS (GUI app)](#macos-gui-app). * **A reachable `svpchain-remote` URL.** svpchain hosts one at `https://indexer.svpchain.com/mcp` (used in the configs below). If your team runs its own, ask them for the URL and use that instead. * **The signer binary.** Download the prebuilt build for your machine from the [releases page](https://github.com/svpchain/svpchain-signer-mcp/releases/latest) — no Go toolchain or source checkout needed. | Your machine | Download | | --------------------------------------------------- | --------------------------------------------------- | | Linux, x86-64 | `svpchain-signer-mcp--linux-amd64.tar.gz` | | Linux, ARM64 | `svpchain-signer-mcp--linux-arm64.tar.gz` | | macOS (CLI only — prefer [GUI app](#macos-gui-app)) | `svpchain-signer-mcp--darwin-arm64.tar.gz` | The signer is a **command-line program** — on macOS, the [GUI app](#macos-gui-app) is easier. If you use the CLI tarball on Mac anyway, don't double-click it in Finder; use a terminal to verify, unpack, and install. Replace `` with the file you downloaded: ```bash shasum -a 256 -c SHA256SUMS # verify (Linux: sha256sum -c SHA256SUMS) ``` ```bash tar -xzf .tar.gz # unpack the binary ``` ```bash chmod +x # make it executable ``` ```bash ./ --help # confirm it runs — prints the signer's usage ``` On macOS the `--help` run may be blocked the first time ("cannot be opened because the developer cannot be verified" — the binary isn't notarized). Clear the quarantine flag once and retry: ```bash xattr -d com.apple.quarantine ``` **You don't launch the signer yourself — your MCP client starts it for you.** Move the binary somewhere stable (not your Downloads folder). We recommend installing it as `/usr/local/bin/svpchain-signer-mcp` (you can pick another path if you prefer — just use that same absolute path consistently in the steps below): ```bash sudo mv /usr/local/bin/svpchain-signer-mcp ``` ```bash sudo chmod +x /usr/local/bin/svpchain-signer-mcp ``` ```bash /usr/local/bin/svpchain-signer-mcp --help # confirm the installed path works ``` > **No prebuilt CLI build for Windows or Intel (x86) Macs.** On Windows, run the signer under WSL with the Linux x86-64 download. On an Intel Mac, build from source below — the Apple Silicon build won't run on Intel. Intel Mac users can also try the GUI builds on the [releases page](https://github.com/svpchain/svpchain-signer-mcp/releases/) if one is available for their chip. ### Build from source (CLI only) Prefer to build the signer yourself — for an Intel Mac, or to audit and reproduce the key-holding binary? This repository *is* the signer's source. Building needs only Go 1.23+ and a C toolchain (CGO — the signer links libsecp256k1). This is also how an Intel Mac gets a working binary: ```bash git clone https://github.com/svpchain/svpchain-signer-mcp.git cd svpchain-signer-mcp CGO_ENABLED=1 go build -trimpath -o svpchain-signer-mcp . sudo mv svpchain-signer-mcp /usr/local/bin/svpchain-signer-mcp ``` ## Import your key (CLI only) Skip this section if you used **`svpchain signer.app`** on macOS — the app imports your key for you. Load your private key into the OS credential store **once**, so your client config never has to carry it — the signer reads it from there at startup. Use the installed binary path (we use `/usr/local/bin/svpchain-signer-mcp` throughout) and the chain id your `svpchain-remote` is on (`svp-2517-1` in the configs below — confirm with whoever runs your remote): ```bash /usr/local/bin/svpchain-signer-mcp import --chain-id svp-2517-1 Enter private key (hidden): Stored key for svp1… (svp-2517-1) ``` The key is saved in your OS credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service) under the chain id — **one key per chain**. Re-running `import` overwrites it (that's how you rotate). `list` and `delete` manage stored keys: ```bash /usr/local/bin/svpchain-signer-mcp list # stored chain ids /usr/local/bin/svpchain-signer-mcp delete --chain-id svp-2517-1 # remove a key ``` > **Headless / server hosts** without a secret-service daemon (some Linux or CI setups) can skip `import` and instead add an `env` block to the signer entry — `"env": { "SIGNER_KEY_HEX": "" }` — or export `SIGNER_KEY_HEX` before the client launches it. On a normal desktop, prefer `import` so the key never lands in a config file. ## Install in your client (CLI) If you set up via **`svpchain signer.app`** on macOS, paste the MCP JSON the app generated — you can skip the manual blocks below except for adding **`svpchain-remote`** if needed. Each section is a copy-paste config block for **CLI** installs. After saving, restart the client; you should see `svpchain-remote` and `svpchain-signer` in the client's MCP tool list. ### Claude Code In any directory: ```bash claude mcp add-json -s user svpchain-signer '{ "command": "/usr/local/bin/svpchain-signer-mcp", "args": ["--chain-id", "svp-2517-1"] }' ``` ```bash claude mcp add-json -s user svpchain-remote '{ "type": "http", "url": "https://indexer.svpchain.com/mcp" }' ``` No key in the config — you imported it above. Re-running `add-json` overwrites the entry — safe for switching URLs or chain ids. ### Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux): ```json { "mcpServers": { "svpchain-signer": { "command": "/usr/local/bin/svpchain-signer-mcp", "args": [ "--chain-id", "svp-2517-1" ] }, "svpchain-remote": { "type": "http", "url": "https://indexer.svpchain.com/mcp" } } } ``` Quit Claude Desktop fully (⌘Q on macOS — not just close the window) and relaunch. ### Cursor Edit `~/.cursor/mcp.json` (same JSON shape as Claude Desktop above): ```json { "mcpServers": { "svpchain-signer": { "command": "/usr/local/bin/svpchain-signer-mcp", "args": [ "--chain-id", "svp-2517-1" ] }, "svpchain-remote": { "type": "http", "url": "https://indexer.svpchain.com/mcp" } } } ``` In Cursor, open **Settings → MCP** to see the servers appear with green status dots. ### Windsurf Edit `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "svpchain-signer": { "command": "/usr/local/bin/svpchain-signer-mcp", "args": [ "--chain-id", "svp-2517-1" ] }, "svpchain-remote": { "type": "http", "url": "https://indexer.svpchain.com/mcp" } } } ``` Reload the Windsurf window after saving. ### Cline (VS Code) Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` (macOS) or the Linux equivalent under `~/.config/Code/...`. Same JSON shape as the other clients above. ### Continue (VS Code / JetBrains) Edit `~/.continue/config.json`. Same JSON shape. ## Verify the connection Start a new chat and try these prompts, in order. Each one exercises a different layer. **1. Confirm both servers are connected and learn your svpchain address.** #### Prompt ```prompt Call `whoami` on the svpchain-remote server and `whoami` on the svpchain-signer. Show me both outputs. ``` You should see two responses with the same `owner` address — that `svp1…` string is your svpchain address, derived deterministically from your MetaMask key. Save it; you'll need it any time you fund the account or look it up on a block explorer. If the two `owner` values *differ*, your signer is loading a different key from the one the remote session was authenticated for — re-check which key you imported (re-import through the macOS app or re-run `import` with the right key). **2. Read live chain state (no signing required).** #### Prompt ```prompt Get the BTC-USD orderbook and oracle price. ``` This hits read-only tools on the remote — markets, orderbook, oracle. If it works your network path to the chain + indexer is healthy. **3. End-to-end: build → sign → broadcast.** #### Prompt ```prompt Deposit 1 USDC from my bank balance into subaccount 0. ``` The agent should call `build_deposit_to_subaccount` (remote) → `sign_transaction` (signer) → `broadcast_signed_tx` (remote). Confirm the tx hash, then check the new balance with `get_live_subaccount`. **4. (Negative) Confirm the safety caps fire.** #### Prompt ```prompt Deposit 2000 USDC into subaccount 0. ``` This should be rejected by the remote server's `deposit_max_usdc` cap *before* anything is signed — you'll see a clear error, no transaction on chain. ## How auth works You don't configure a bearer token. The first time your agent calls a tool that needs auth on a given session, it goes through this flow under the hood: 1. **`auth_challenge(owner)`** on `svpchain-remote` returns a one-time challenge string scoped to the chain and a short TTL. 2. **`sign_challenge(challenge)`** on `svpchain-signer` signs it with your key. The signer refuses anything that doesn't have the svpchain-mcp challenge prefix, so the same key can't be tricked into signing a transaction-shaped message. 3. **`auth_verify(nonce, signature)`** on the remote recovers the address from the signature, checks it matches the claimed owner, mints a bearer with a 24-hour TTL, and binds it to your MCP session. Subsequent tool calls on the same session are authenticated automatically. If your agent gets cut off mid-session and has to reconnect, the flow re-runs transparently on the next call. ## Troubleshooting * **"missing tenant context"** — The session hasn't completed the auth handshake yet. The remote binds a tenant to your session only after `auth_challenge` → `sign_challenge` → `auth_verify` succeed (see *How auth works* above), and **every** tool call needs it — including read-only ones like `whoami` or `get_oracle_price`. GUI clients (Claude Code, Cursor, …) handle this for you: the agent calls the `auth_*` tools on its first failure. If you see this error persistently, it's almost always one of: * **A programmatic / SDK client that never runs the handshake.** Make sure your agent actually calls `auth_challenge`/`sign_challenge`/ `auth_verify` (give it a system prompt describing the flow if it doesn't do so on its own), and that tool errors are surfaced back to the agent rather than aborting the run — otherwise it can't react and authenticate. * **The handshake and the tool call land on different sessions.** The tenant is bound to one `Mcp-Session-Id`; if your client opens a fresh connection per call (e.g. langchain's `get_tools()` instead of a persistent `client.session(...)`), the authenticated tenant is lost. Keep one session open across the whole run. * **"recovered address does not match the owner this nonce was issued to"** — the key you imported corresponds to a different address than the `owner` your prompt claimed. Re-import the right key, or use the matching owner. * **"payload.chain\_id ... does not match signer --chain-id ..."** — The `--chain-id` baked into your client config doesn't match the chain the remote server is talking to. Ask whoever runs the `svpchain-remote` you're pointed at for the right chain id (or look at the `chain_id` field in their `mcp.toml`), then update the `--chain-id` arg in your signer config to match. * **"account sequence mismatch"** — Two funds transactions raced. Have the agent call `get_tx_status` between sends, or pause a couple of seconds. The remote server reads the committed sequence at build time; the previous tx needs to land first. * **Tools list shows no svpchain servers** — Your client's config path is wrong, or the JSON is malformed. Re-check the path against your client's section above and validate the JSON. * **Signer exits with "no signing key for ..."** — you haven't imported a key for that chain id yet (or it's under a different chain id). On macOS, re-import through **`svpchain signer.app`**. On CLI setups, run the **Import your key** step above, or check `/usr/local/bin/svpchain-signer-mcp list`. * **"invalid key: ..." during `import`** — the key must be 64 hex characters. A leading `0x` is fine; spaces and quotes around the value are not. Re-export from MetaMask if in doubt. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://svpchain.gitbook.io/svpchain-docs/agents/client-setup.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.