# Somnia MCP server

> somnia mcp serves Somnia Markets to AI agents over the Model Context Protocol: read tools for markets, books, positions, prices and the Explorer, and a guide to every Somnia CLI command. It never signs or sends a transaction.

**Somnia Markets as tools for your agent.**

The Somnia MCP server ships inside the [Somnia CLI](/build/cli) as `somnia mcp`. It speaks the Model Context Protocol over stdio, so Claude Code, Codex, Cursor and any other MCP client can read markets, order books, positions, prices and the Explorer, and find the right CLI command for anything else.

The server never signs or sends anything. Every transaction goes through the CLI, under a signer you choose, so nothing touches funds without the key you set up.

## Set it up

The server needs [Node.js](https://nodejs.org) 22 or newer. Your MCP client starts it, so there is nothing to run yourself.

**Claude Code:**

```sh
claude mcp add somnia -- npx -y @somnia-chain/cli mcp
```

**Codex:**

```sh
codex mcp add somnia -- npx -y @somnia-chain/cli mcp
```

**Cursor, Claude Desktop and other clients** that take a JSON config (in Cursor, `.cursor/mcp.json` in your project or `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "somnia": {
      "command": "npx",
      "args": ["-y", "@somnia-chain/cli", "mcp"]
    }
  }
}
```

If you installed the CLI with `npm install -g @somnia-chain/cli`, use `somnia mcp` as the command instead of `npx`:

```sh
claude mcp add somnia -- somnia mcp
```

The read tools go to mainnet unless a call names a network. To make testnet the default, add `--network testnet` after `mcp`, or set `SOMNIA_NETWORK=testnet` in the server's environment. `--rpc-url`, `--indexer-url`, `--oracle-url` and `--explorer-url` point the tools at other endpoints than the preset's.

## What your agent can do

Each read tool runs the matching CLI command and returns its JSON along with the command line, so the agent learns the CLI as it goes.

| Tool | What it reads |
| --- | --- |
| `markets` | Markets of every kind, newest first |
| `spot_book` | A spot pool's resting book, and its tick and lot grid |
| `spot_portfolio` | A wallet's spot open orders, pending stop orders and recent trades |
| `binary_markets` | Binary markets trading now, past or all, with filters |
| `binary_market` | One binary market: its indexed row, live state, ids and payout |
| `binary_positions` | An account's open binary positions, with cost basis, mark and PnL |
| `perp_markets` | Perp markets, and whether each is tradeable |
| `perp_account` | A cross-margin account's collateral, equity, margin and positions |
| `token_balance` | An account's balance of an ERC-20, or of an ERC-6909 id |
| `price` | An asset's oracle feed, and its latest spot and mark price |
| `fills` | An account's fills as maker or taker, newest first |
| `venue_health` | A grade for the venue (ok, degraded or down) from the indexer, chain and price feed |
| `explorer_address` | An address on the [Explorer](/blockchain/explorer): balance, contract or account, creator, token |
| `explorer_transaction` | A transaction: status, block, sender, recipient, value, fee and token transfers |
| `explorer_block` | A block by number or hash |
| `explorer_token` | A token: name, symbol, type, decimals, supply and holders |
| `explorer_logs` | Event logs of a transaction or a contract |
| `explorer_search` | Search for an address, transaction, block, token or contract |

Three more tools cover everything else:

- **`somnia_find`** finds the CLI command for a task described in plain words, such as "place a spot order" or "perp funding history".
- **`somnia_help`** shows any command's `--help`: what it does and prints, its flags and examples.
- **`somnia_feedback`** tells the Somnia team about a problem with the CLI or these tools, as `somnia feedback` does. Pass `messageOnly: true` to send the agent's words alone.

## Transactions

The CLI has about 190 commands, including every transaction: orders, cancels, deposits, transfers and lending. For those, the server points the agent to the CLI, which the agent runs from a shell. The CLI signs with the account your environment selects, such as a key in your system keychain, and prints JSON with the transaction's hash, status and block. See [Signing](/build/cli#signing) for every way to give it a key.

To review before anything is sent, export the build signer in the shell you start the agent from, so the CLI commands the agent runs inherit it, and keep any key out of that shell. Put your account's address in place of `<address>`:

```sh
unset SOMNIA_PRIVATE_KEY SOMNIA_SESSION_SEED
export SOMNIA_SIGNER=build:<address>
```

Setting it only in the MCP server's config doesn't reach the agent's shell. The agent's write commands then print unsigned transactions, which you sign with `somnia tx sign` in a separate shell that has your key (for example `SOMNIA_SIGNER=keychain:<name>`), then send with `somnia tx submit`. See [Offline signing](/build/cli#offline-signing).

Try writes on the Global testnet first, with STT from the [testnet faucet](/blockchain/faucet).

## Telemetry

The CLI's usage telemetry is off until the user opts in, and `somnia mcp` never asks. An agent should not turn it on by itself: it asks its user once, says what is shared, and runs `somnia telemetry enable` only on a clear yes. See [Usage telemetry](/build/cli#usage-telemetry).

## Docs for agents

To give an agent the docs as well, point it at [llms.txt](https://new.docs.somnia.network/llms.txt), or [llms-full.txt](https://new.docs.somnia.network/llms-full.txt) for every page in one file. The Explorer's [llms.txt](https://new.explorer.somnia.network/llms.txt) lists its pages and APIs, which need no key.

---

Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.