> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# sauce mcp

> Serve the sauce command's tools and the agent skills to coding agents over MCP, and add the server to a project's agent config files.

`sauce mcp` serves the SDK's tools and agent skills over the [Model Context Protocol](https://modelcontextprotocol.io). Use `sauce mcp setup` to add the server to coding agents' project configuration.

## Synopsis

```bash theme={null}
sauce mcp [--config <file> | --offline] [--wallets <dir> | --no-wallets] [--pots <dir>] [--no-stores]
sauce mcp (--password-env <NAME> | --password-file <path> | --password-command <command>) [--wallets <dir>] [--config <file>]
sauce mcp --http <port> [--host <address>] [--allowed-host <name>]… [--config <file>]
sauce mcp setup [--agent <agent>,…] [--dir <project>] [--config <file>] [--force]
```

## Description

### The server

A coding agent starts `sauce mcp` itself, from its MCP configuration, and talks to it over stdio. Every server, over stdio or HTTP, has these tools and resources:

* the command's building tools: `sauce_chains`, `sauce_globals`, `sauce_price`, `sauce_pools`, `sauce_compile`, `sauce_actions`, `sauce_tx`, `sauce_signed_cook`, `sauce_pot`, `sauce_reclaim`, `sauce_simulate`, `sauce_inspect` and `sauce_verify`;
* `sauce_send`, which broadcasts transactions the caller signed;
* the agent skills as tools (`sauce_skills`, `sauce_skill`, `sauce_dev`, `sauce_install_skills`) and as resources at `sauce://skills/<path>`;
* one prompt, `sauce_write_program`.

No tool takes a key or a password. A transaction comes back unsigned for the user's own wallet, or is sent from one of the server's own wallets. [Tools](https://docs.eco.com/sauce-sdk/mcp/tools.md) lists every tool.

Over stdio the server also has:

* **Wallet tools** for the wallet directory (`--wallets`, default `~/.sauce/wallets`, the one `sauce wallet` uses). `sauce_wallet_list` and `sauce_wallet_address` need no password. `sauce_wallet_create`, `sauce_wallet_import`, `sauce_wallet_send` and `sauce_sign` work once the wallets are enabled. A password source given on the command line enables them at start; without one, the agent enables them with `sauce_wallet_enable`, naming where the password comes from and never the password itself. `sauce_wallet_send` simulates what it is given and holds it to the wallet's policy before it sends, and `sauce_sign` signs a cook for another account to send ([`sauce sign`](https://docs.eco.com/sauce-sdk/cli/sign)). [MCP wallets](https://docs.eco.com/sauce-sdk/mcp/wallets.md) covers them.
* **Store tools**: every Pot that a tool's transaction deploys (`sauce_send`, `sauce_wallet_send`) is recorded in the Pot store (`--pots`, default `~/.sauce/pots`), which `sauce_pot_list` and `sauce_pot_import` read and write, as `sauce pot list` and `sauce pot import` do. `--no-stores` keeps no store, the wallet directory included, and so serves no wallet tool. [Local server storage](https://docs.eco.com/sauce-sdk/mcp/local-server.md) covers them.

With `--http`, the server serves Streamable HTTP at `/mcp`, stateless, on `127.0.0.1` unless `--host` says otherwise, and answers only a loopback `Host` or an `--allowed-host` one. It authenticates no one, so off loopback it needs `--allowed-host` and belongs behind your own authentication. The HTTP server has no signing, wallet or Pot store tools, and refuses `--wallets` and the password flags. [Self-hosting](https://docs.eco.com/sauce-sdk/mcp/self-hosting.md) covers running it for a team.

A tool reads a chain through the caller's `rpcUrl`, else the `--config` entry for the chain, else a built-in public endpoint. Over HTTP the server reads no environment variable. Over stdio it reads the one `--password-env` names, and any one an agent names through `sauce_wallet_enable`'s `env`, using its value only as the wallets' password ([Agents, wallets and keys](https://docs.eco.com/sauce/security-considerations.md#agents-wallets-and-keys)). It never shows a URL from the config file. `--offline` reaches no network of its own: no built-in endpoint, and no install of its packages; a tool then reads a chain only through a caller's `rpcUrl`.

The server's packages, the MCP SDK and `zod`, are optional peer dependencies of the package. The server uses your own copies at the pinned versions, else this version's runtime folder, which its first start installs ([`sauce runtime`](https://docs.eco.com/sauce-sdk/cli/runtime)).

### `sauce mcp setup`

`setup` adds the server to a project, for each agent, in the file its vendor documents:

| Agent | `--agent` | File | Entry |
| - | - | - | - |
| Claude Code | `claude` | `.mcp.json` | `mcpServers.sauce` |
| OpenAI Codex | `codex` | `.codex/config.toml` | `[mcp_servers.sauce]` |
| Cursor | `cursor` | `.cursor/mcp.json` | `mcpServers.sauce` |
| GitHub Copilot in VS Code | `copilot` | `.vscode/mcp.json` | `servers.sauce` |
| Gemini CLI | `gemini` | `.gemini/settings.json` | `mcpServers.sauce` |

The entry launches `npx -y @eco-incorp/sauce@<version> mcp`, where `<version>` is the exact version of the `sauce` that ran `setup`. A project file is shared, so it names no command a machine must have installed, and it runs the version whose skills the project installed. `--config <file>` adds `--config <file>` to the entry's arguments. The entry starts the server with no wallet flags: it serves the wallet directory `~/.sauce/wallets`, with no password source.

Existing files are handled as follows:

* Everything else in a file is kept.
* An entry that is already there is reported `unchanged`.
* A `sauce` entry that differs is kept, unless you pass `--force`.
* A JSON file that is not plain JSON, such as one with a comment, is refused, and `setup` exits `2` with the entry to add by hand. It stops there: the files for the agents before it are already written, and those after it are not. For every agent, an unparseable `.cursor/mcp.json` leaves `.mcp.json` and `.codex/config.toml` written, and no `.vscode/mcp.json` or `.gemini/settings.json` ([example](#a-file-setup-cannot-edit)).

Each agent applies its own trust rules before it runs a project's server. `setup` prints the one for Codex: Codex reads `.codex/config.toml` only in a project it trusts. `setup` also installs the runtime folder, so an agent's first start of the server does not wait for it.

To add the server to your user configuration instead of the project's, use the agent's own command:

```bash theme={null}
claude mcp add sauce -- sauce mcp    # Claude Code
codex mcp add sauce -- sauce mcp     # OpenAI Codex
gemini mcp add sauce sauce mcp       # Gemini CLI
```

Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`) take the entry `"sauce": { "command": "sauce", "args": ["mcp"] }` under `mcpServers`; VS Code (`.vscode/mcp.json`) takes it under `servers`. `sauce` is a Node.js script that starts with `#!/usr/bin/env node`, so a desktop client that does not have your shell's `PATH` needs both: the absolute path `which node` prints as `command`, and the path `which sauce` prints, then `mcp`, as `args`. [MCP overview](https://docs.eco.com/sauce-sdk/mcp/overview.md) covers each agent.

## Options

| Option | Description |
| - | - |
| `--config <file>` | Your own RPC endpoints: `{ "rpcUrls": { "<chain id>": "<url>" } }` (default: the built-in public ones). With `setup`, added to the entry's arguments. |
| `--offline` | Reach no network of its own: no built-in endpoint, and no install. |
| `--http <port>` | Serve Streamable HTTP on this port instead of stdio (`0` picks a free port). |
| `--host <address>` | With `--http`: the interface to bind (default `127.0.0.1`). |
| `--allowed-host <name>` | With `--http`: a `Host` it answers besides loopback's. Required off loopback; `'*'` answers any. Repeatable. |
| `--max-body <bytes>` | The largest message it reads, over either transport (default 2 MiB). |
| `--allow-private-rpc` | With `--http`: let a caller's `rpcUrl` be `http:` or a private address, for a private deployment. |
| `--wallets [<dir>]` | Over stdio: the wallet directory its wallet tools serve (default `~/.sauce/wallets`). |
| `--no-wallets` | Over stdio: serve no wallet tools; nothing signs. |
| `--password-env <NAME>` | The wallet password is the environment variable `NAME`. |
| `--password-file <path>` | Or a file only you can read. |
| `--password-command <command>` | Or what this command prints, such as a secret manager's CLI. |
| `--pots <dir>` | Over stdio: keep the Pot store here (default `~/.sauce/pots`, which `sauce pot list` reads). |
| `--no-stores` | Over stdio: keep none of the command's stores (by default it keeps them, as `sauce` does). |
| `--agent <agent>` | With `setup`: `claude`, `codex`, `cursor`, `copilot`, `gemini` or `all`, comma-separated (default `all`). |
| `--dir <project>` | With `setup`: the project (default `.`). |
| `--force` | With `setup`: replace a `sauce` entry that differs. |
| `-h, --help` | Show the help. |
| `--no-update-check` | Print no notice of a newer `sauce`, and do not read the registry for one. |

## Output

Over stdio the server writes only the protocol to stdout; its messages go to stderr. A message larger than `--max-body` closes the connection. With `--http` it prints the URL it serves on stderr. The server prints no update notice: when the update cache names a newer release, the first tool result of the server's life carries one note about it.

`setup` prints one line per file with its state (`wrote`, `unchanged`, `kept`, `overwrote`) and the agent it is for.

An invalid combination of flags exits 2 before the server starts:

```text theme={null}
sauce mcp: --wallets is for stdio: the HTTP server never signs, and serves no wallet tools
sauce mcp: --offline reads no chain: give it without --config
sauce mcp: --wallets goes with wallets, not --no-wallets
sauce mcp: --host 0.0.0.0 is beyond loopback: name the host the server is served as with --allowed-host <name> (or --allowed-host '*' behind a proxy that checks the Host itself)
```

## Examples

### Add the server to a project for every agent

```bash theme={null}
sauce mcp setup --dir mcpproj
```

```text theme={null}
The @eco-incorp/sauce MCP server, in mcpproj:
  wrote     .mcp.json              (claude)
  wrote     .codex/config.toml     (codex)
  wrote     .cursor/mcp.json       (cursor)
  wrote     .vscode/mcp.json       (copilot)
  wrote     .gemini/settings.json  (gemini)
Codex reads .codex/config.toml only in a project it trusts.
```

The files it wrote:

```json .mcp.json theme={null}
{
  "mcpServers": {
    "sauce": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@eco-incorp/sauce@<version>", "mcp"]
    }
  }
}
```

```toml .codex/config.toml theme={null}
[mcp_servers.sauce]
command = "npx"
args = ["-y", "@eco-incorp/sauce@<version>", "mcp"]
```

```json .cursor/mcp.json theme={null}
{
  "mcpServers": {
    "sauce": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@eco-incorp/sauce@<version>", "mcp"]
    }
  }
}
```

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "sauce": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@eco-incorp/sauce@<version>", "mcp"]
    }
  }
}
```

```json .gemini/settings.json theme={null}
{
  "mcpServers": {
    "sauce": {
      "command": "npx",
      "args": ["-y", "@eco-incorp/sauce@<version>", "mcp"]
    }
  }
}
```

Run again, `setup` reports each file `unchanged` and writes nothing.

### Replace an entry that differs

When `.mcp.json` already names a `sauce` server with other arguments, `setup` keeps it:

```bash theme={null}
sauce mcp setup --dir mcpproj --agent claude
```

```text theme={null}
The @eco-incorp/sauce MCP server, in mcpproj:
  kept      .mcp.json  (claude): it already names a "sauce" server, which differs; edit it, or --force replaces a JSON entry or a [mcp_servers.sauce] table
```

`--force` replaces the `sauce` entry and keeps the file's other servers:

```bash theme={null}
sauce mcp setup --dir mcpproj --agent claude --force
```

```text theme={null}
The @eco-incorp/sauce MCP server, in mcpproj:
  overwrote .mcp.json  (claude)
```

To move a project's entry to the latest release, run `npx -y @eco-incorp/sauce@latest mcp setup --force`.

### A file setup cannot edit

When `.cursor/mcp.json` holds something other than plain JSON, `setup` refuses it and stops:

```bash theme={null}
sauce mcp setup --dir setupproj
```

```text theme={null}
sauce mcp: .cursor/mcp.json is not plain JSON (a comment in it, perhaps), so setup leaves it alone: add "sauce": {"type":"stdio","command":"npx","args":["-y","@eco-incorp/sauce@<version>","mcp"]} under "mcpServers" yourself
Run `sauce mcp --help` for usage.
```

It exits `2`. `.mcp.json` and `.codex/config.toml` were written before it; `.vscode/mcp.json` and `.gemini/settings.json` were not. Add the entry to `.cursor/mcp.json` by hand, then run `sauce mcp setup --dir setupproj --agent copilot,gemini` for the agents after it.

### Set up two agents with your own endpoints

```bash theme={null}
sauce mcp setup --dir mcpproj2 --agent claude,cursor --config rpc.json
```

```text theme={null}
The @eco-incorp/sauce MCP server, in mcpproj2:
  wrote     .mcp.json         (claude)
  wrote     .cursor/mcp.json  (cursor)
```

```json .mcp.json theme={null}
{
  "mcpServers": {
    "sauce": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@eco-incorp/sauce@<version>", "mcp", "--config", "rpc.json"]
    }
  }
}
```

### Serve over HTTP on loopback

```bash theme={null}
sauce mcp --http 0 --offline
```

```text theme={null}
sauce mcp: Streamable HTTP at http://127.0.0.1:<port>/mcp (stateless, no authentication)
```

## Next steps

* [MCP overview](https://docs.eco.com/sauce-sdk/mcp/overview.md)
* [Tools](https://docs.eco.com/sauce-sdk/mcp/tools.md)
* [MCP wallets](https://docs.eco.com/sauce-sdk/mcp/wallets.md)
* [Local server storage](https://docs.eco.com/sauce-sdk/mcp/local-server.md)
* [Self-hosting](https://docs.eco.com/sauce-sdk/mcp/self-hosting.md)
* [External wallets](https://docs.eco.com/sauce-sdk/mcp/external-wallets.md)
* [`sauce runtime`](https://docs.eco.com/sauce-sdk/cli/runtime)
* [`sauce skills`](https://docs.eco.com/sauce-sdk/cli/skills)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.