fugu-mcp

fugu-mcp

An MCP 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).

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:

{
  "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:

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:

{
  "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:

{
  "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.

---

Configuration (environment variables)

All config is via env. Copy .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 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, 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:

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

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)