# fugu-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes **Sakana Fugu** — an OpenAI-compatible orchestration LLM — as on-demand **tools** inside Claude Code. Use it to pull a second opinion or run a small multi-model panel on a discrete, self-contained subproblem, without leaving your Claude Code session.

> **Fugu is a tool, not the driver.** This does **not** make Fugu the main model for Claude Code. Claude Code only drives on Anthropic / Bedrock / Vertex / Foundry models. fugu-mcp lets the Claude main loop *call out* to Fugu on demand — it is a narrow tool, not a model swap.

---

## What you get

Two tools, both backed by Sakana's `POST /v1/chat/completions` endpoint:

| Tool | Use it for |
|------|-----------|
| `ask_fugu` | A general second opinion on a hard, self-contained question (tricky algorithm, design trade-off, "is my approach sound?"). |
| `fugu_second_opinion` | A review-shaped critique: hand it `content` (code, diff, answer, plan) plus a `question`, get back a skeptical senior-reviewer pass. |

Plus a `/fugu` slash command for manual invocation.

---

## Install

Requires Node 20+ (Node 26 recommended; uses native `fetch`).

```bash
git clone https://github.com/<your-org>/fugu-mcp.git
cd fugu-mcp
npm install
npm run build            # tsc -> dist/

export SAKANA_API_KEY=...   # your real key; never commit it

# run from the repo root so $(pwd) resolves to your clone
claude mcp add fugu -- node "$(pwd)/dist/index.js"
```

Then in Claude Code, e.g.: *"Ask Fugu to cross-check this approach."*

`claude mcp add` inherits your shell environment, so the exported `SAKANA_API_KEY` (and any `FUGU_*` overrides) flow through to the server.

### Alternative: `.mcp.json`

To check the registration into a project (so collaborators get it automatically), add a `.mcp.json` at the repo root instead of running `claude mcp add`. A ready-to-edit template lives at [`.mcp.json.example`](./.mcp.json.example):

```json
{
  "mcpServers": {
    "fugu": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "SAKANA_API_KEY": "REPLACE_WITH_YOUR_SAKANA_API_KEY",
        "FUGU_BASE_URL": "https://api.sakana.ai/v1",
        "FUGU_DEFAULT_MODEL": "fugu-ultra",
        "FUGU_TIMEOUT_MS": "120000"
      }
    }
  }
}
```

> Do **not** commit a real `SAKANA_API_KEY` in `.mcp.json`. Either keep `.mcp.json` out of version control, or leave the placeholder and set the real key via the environment (the server reads `process.env.SAKANA_API_KEY` regardless of where the session is launched).
>
> `args` uses a relative `dist/index.js`; this resolves against the directory Claude Code is launched from. Use an absolute path (`/path/to/fugu-mcp/dist/index.js`) if you run sessions from elsewhere.

### Use with OpenClaw

OpenClaw supports MCP natively, so the **same server** works there — no separate build. After `npm run build`:

```bash
openclaw mcp add fugu \
  --command node \
  --arg "/path/to/fugu-mcp/dist/index.js" \
  --env SAKANA_API_KEY=your_key_here
```

`openclaw mcp add` probes the server before saving. Confirm with `openclaw mcp list`, and the `ask_fugu` / `fugu_second_opinion` tools become available to your OpenClaw agents. Run `openclaw mcp reload` after changing config so the new settings take effect on the next turn.

---

## Tools

### `ask_fugu`

A general second opinion / hard self-contained query. The prompt must contain **everything** Fugu needs — it cannot see your repo, files, or the current conversation.

| Argument | Type | Required | Default | Notes |
|----------|------|----------|---------|-------|
| `prompt` | string | yes | — | The full, self-contained problem or question. |
| `system_prompt` | string | no | — | Steer Fugu's role/behavior. |
| `model` | `"fugu"` \| `"fugu-ultra"` | no | `FUGU_DEFAULT_MODEL` | Pick a specific model. |
| `max_tokens` | integer > 0 | no | `2000` | Max output tokens. |

Example invocation:

```json
{
  "name": "ask_fugu",
  "arguments": {
    "prompt": "I'm choosing between a single-writer WAL and a per-shard log for a 50k-writes/sec ledger. Walk through the durability/throughput trade-offs and recommend one. Assume NVMe and fsync-per-commit.",
    "system_prompt": "You are a senior distributed-systems engineer.",
    "model": "fugu-ultra",
    "max_tokens": 1500
  }
}
```

In conversation you can just say: *"Use ask_fugu to sanity-check this proof."*

### `fugu_second_opinion`

A review-shaped critique. Wraps a skeptical-senior-reviewer system prompt internally, so you only supply the material and the question.

| Argument | Type | Required | Default | Notes |
|----------|------|----------|---------|-------|
| `content` | string | yes | — | The material to review: code, a diff, an answer, a design, or a plan. |
| `question` | string | yes | — | What you want assessed. |
| `model` | `"fugu"` \| `"fugu-ultra"` | no | `FUGU_DEFAULT_MODEL` | Pick a specific model. |

Example invocation:

```json
{
  "name": "fugu_second_opinion",
  "arguments": {
    "content": "func transfer(from, to *Account, amt int) {\n  from.mu.Lock(); to.mu.Lock()\n  from.bal -= amt; to.bal += amt\n  from.mu.Unlock(); to.mu.Unlock()\n}",
    "question": "Is this concurrency-safe?",
    "model": "fugu-ultra"
  }
}
```

In conversation: *"Get a fugu_second_opinion on this diff — is the error handling complete?"*

### `/fugu` slash command

`/fugu <your question>` routes your text to `ask_fugu` and asks Claude to summarize Fugu's answer and note where it agrees or disagrees — treating Fugu as one voice in a panel, not ground truth. See [`.claude/commands/fugu.md`](./.claude/commands/fugu.md).

---

## Configuration (environment variables)

All config is via env. Copy [`.env.example`](./.env.example) to `.env` for local use (`.env` is gitignored).

| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|
| `SAKANA_API_KEY` | yes (at call time) | — | Sent as `Authorization: Bearer <key>`. Optional at startup so the server can boot and answer `tools/list`; a missing key surfaces as a clear tool error only when a tool is actually called — it never crashes the process. **Env only; never write a real key to a tracked file.** |
| `FUGU_BASE_URL` | no | `https://api.sakana.ai/v1` | OpenAI-compatible base URL. Requests go to `<base>/chat/completions`. |
| `FUGU_DEFAULT_MODEL` | no | `fugu-ultra` | Model used when a tool call omits `model`. |
| `FUGU_TIMEOUT_MS` | no | `120000` | Per-request timeout in milliseconds. Orchestrators are slow; the default is generous. |

A malformed `FUGU_BASE_URL` (not a URL) or non-positive `FUGU_TIMEOUT_MS` fails fast at startup with a clear message. A missing key does **not**.

---

## Hooks (for working *on* this repo)

This repo ships [`.claude/settings.json`](./.claude/settings.json) with hooks that keep the build green and guard secrets while you edit fugu-mcp itself:

- **PreToolUse** on `Write | Edit | Bash` → runs [`scripts/guard-secrets.sh`](./scripts/guard-secrets.sh), which scans the payload for an API-key pattern and **blocks** the operation if a real-looking key is detected (so a key can't be written into a file or slipped into a commit).
- **PostToolUse** on `Edit | Write | MultiEdit` → runs `npm run typecheck` (non-blocking; keeps types green during edits).

These hooks are for development of fugu-mcp; they are not required to *use* the MCP server in another project.

---

## `MCP_TIMEOUT` for the consuming session

Fugu calls can take tens of seconds (up to ~120s). Claude Code's default MCP startup/tool timeout can be too short. In the session that **consumes** this server, set:

```bash
export MCP_TIMEOUT=120000
```

This raises Claude Code's MCP timeout to match the server's own `FUGU_TIMEOUT_MS` default, so slow Fugu responses aren't cut off.

---

## Standalone vs integrated

**Use Fugu standalone when:** you want a one-shot answer and you're happy outside Claude Code. Drive Sakana's OpenAI-compatible API directly from Codex, Cursor, or `curl`. That path is simpler and avoids a hop.

**Use this MCP tool when:** you're already mid-task in Claude Code and want a *narrow second opinion* — a different model's take on a discrete, self-contained subproblem — without breaking flow. fugu-mcp is deliberately small: two tools, second-opinion shaped, no repo access.

Trade-offs to keep in mind:

- **Latency.** Going through the Claude orchestrator adds a hop, and Fugu itself is slow (tens of seconds, occasionally up to ~120s). It is not for tight iteration loops.
- **Cost.** Fugu output is roughly **~$30 / 1M output tokens**. `max_tokens` defaults are kept modest (`ask_fugu` defaults to 2000); keep prompts and outputs tight.
- **Region.** Sakana's API is **blocked in the EU/EEA**. If you're in that region you won't be able to call it.
- **Model IDs.** This server defaults to `fugu-ultra` and exposes `fugu` / `fugu-ultra`. **Verify the exact, current Fugu model IDs and endpoint against the Sakana docs** — they can change. If they differ, it's a config edit (`FUGU_DEFAULT_MODEL`, `FUGU_BASE_URL`), not a code change.

---

## Development

```bash
npm run build        # compile TypeScript to dist/
npm run typecheck    # tsc --noEmit
npm test             # vitest run (mocked fetch; no network, no key needed)
npm start            # node dist/index.js (stdio server)
```