# Soma MCP Server

Give your AI agent the one thing it can't do for itself: **actually run code against tests and prove it passed.**

Soma is an execution-verified code service. This MCP server exposes two tools:

- **`soma_verify_code`** — run candidate code against tests inside an isolated sandbox; get a PASS/FAIL verdict plus a signed, offline-checkable certificate (Ed25519). Use it to independently confirm code works before trusting it.
- **`soma_generate_verified_code`** — ask Soma to write code for a task; when the task is verifiable, the returned code has already been executed against derived tests, with a certificate attached.

15+ languages are supported for verification (Python, JavaScript/TypeScript, Go, C/C++, Java, Rust, Ruby, PHP, Bash, and more).

## Install

Requires Node.js 18+. Runs over stdio.

Add to your MCP client config (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "soma": {
      "command": "npx",
      "args": ["-y", "soma-verify-mcp"],
      "env": {
        "SOMA_API_KEY": "YOUR_SOMA_KEY"
      }
    }
  }
}
```

- **Claude Desktop**: `Settings → Developer → Edit Config`, add the block above, restart.
- **Cursor**: `Settings → MCP → Add`, or drop the same block in `~/.cursor/mcp.json`.

## Configuration

| Env var | Required | Default | Purpose |
|---|---|---|---|
| `SOMA_API_KEY` | yes | — | Your Soma API key. |
| `SOMA_BASE_URL` | no | `https://170-9-236-56.sslip.io` | Soma API base URL. |
| `SOMA_TIMEOUT_MS` | no | `300000` | Per-request timeout. |

Get a free preview key: contact **centrum.arvind@gmail.com** (free tier during the preview).

## Tools

### `soma_verify_code`
Run code against tests and return a signed verdict.

- `language` (string) — e.g. `python`, `javascript`, `go`, `rust`.
- `code` (string) — the complete source to verify.
- `tests` (array) — one of:
  - **function mode** (default): `[{ "input": [arg1, arg2], "expected": value }]` plus `entrypoint` (the function name).
  - **stdio mode**: set `mode: "stdio"` and `[{ "stdin": "...", "expected_stdout": "..." }]`; no entrypoint.
- `entrypoint` (string, optional) — function name for function mode.
- `mode` (`"function"` | `"stdio"`, optional).

Returns: `verdict`, `tests_passed`, `tests_total`, and a `signature` / `public_key` / `sig_alg` you can check offline.

### `soma_generate_verified_code`
Get code for a task, executed against derived tests before it's returned.

- `prompt` (string) — the coding task. **Include concrete input/output examples** (e.g. `>>> f(2) == 4`) so the result is verifiable rather than best-effort.
- `max_tokens` (int, optional, default 1500).

Returns: the code, `certified` (bool), and a `certificate` (`verdict`, `tests_passed`, `tests_total`) when verification passed. If a task isn't verifiable, output is returned uncertified and clearly labeled — never a false "verified".

## What the certificate means

A certificate attests that the listed tests passed inside an isolated sandbox at generation time. It is signed (Ed25519) and checkable offline against the returned public key. It is not a warranty of fitness for any purpose — review output before production use.

## Privacy

No training on your prompts. See the Soma Privacy & Data Policy at `${SOMA_BASE_URL}/privacy`.

## License

MIT.