kairoseki 0.2.0

English · Español

An MCP firewall that stops prompt-injection data theft by tracking where data came from,
not by guessing what attacks look like.

In One Piece, kairoseki (seastone) cancels Devil Fruit powers. Kairoseki does the same for your agent's most dangerous power: reading something an attacker wrote, and then quietly sending your data somewhere.

pipx install kairoseki      # or: uv tool install kairoseki
kairoseki scan              # what can a single prompt injection do with your MCP setup?
kairoseki wrap              # put every MCP server in your Claude / Cursor / VS Code config behind Kairoseki
kairoseki attack            # replay 9 real-world attacks against your setup and get a grade

Why

An agent is exploitable by design when it has all three legs of the lethal trifecta:

1. access to private data (your files, repos, inbox),
2. exposure to untrusted content (a web page, a GitHub issue, an email), and
3. a way to send data out (HTTP, email, a comment, a pull request).

Plug a filesystem server and a fetch server into Claude Code, Cursor or Claude Desktop and you have all three. This keeps happening in the real world:

Most defenses scan text for attack patterns, and attackers just rephrase. Kairoseki breaks the trifecta instead. The idea is inspired by CaMeL (Google DeepMind): track taint across the whole session and step in exactly when untrusted content, private data and an outbound channel meet.

What it does

It is a transparent stdio proxy that speaks raw JSON-RPC, so it works with any MCP server and client, in both the handshake era (initialize, 2024-11-05 → 2025-11-25) and the modern era (server/discover, 2026-07-28). Two dependencies: pyyaml and rich.

Quickstart

0. Prerequisites

1. Install

uv tool install kairoseki
# or: pipx install kairoseki
# or try it without installing: uvx kairoseki scan
# latest from GitHub: uv tool install git+https://github.com/AnthonyRiveraI/kairoseki

Then make sure the kairoseki command is on your PATH, and open a new terminal:

uv tool update-shell     # or: pipx ensurepath
kairoseki --version      # should print: kairoseki 0.1.2

kairoseki: command not found, or your MCP client can't start it? The tool lives in ~/.local/bin (%USERPROFILE%\.local\bin on Windows). Run uv tool update-shell, then fully restart your terminal and your MCP client so they pick up the new PATH. kairoseki wrap also writes the absolute path into your config, which avoids the problem entirely.

To update later: uv tool upgrade kairoseki (or pipx upgrade kairoseki).

Windows: close your MCP client (or disable its Kairoseki-wrapped servers) before upgrading. While a client is running kairoseki.exe, Windows locks the file and uv tool upgrade fails with os error 32.

2. See your exposure

kairoseki scan

It reads the MCP configs of Claude Desktop, Claude Code, Cursor, Windsurf and VS Code, starts each server, and labels every tool as private, untrusted, sink and/or destructive. For Claude Code that includes project servers (.mcp.json), user servers and the current project's local servers in ~/.claude.json; add --all-projects to include every project's local servers.

3. Wrap your servers

kairoseki wrap            # all detected configs (a .kairoseki.bak backup is written first)
kairoseki wrap --remote  # also remote (HTTP/SSE) servers, bridged with mcp-remote (needs Node.js)
kairoseki wrap --undo     # restore
kairoseki status          # which servers are protected, and what each live session has seen

Or wrap a single server by hand. Every client uses the same pattern, kairoseki run --name <name> -- <original command>:

{
  "mcpServers": {
    "fetch": {
      "command": "kairoseki",
      "args": ["run", "--name", "fetch", "--", "uvx", "mcp-server-fetch"]
    }
  }
}

With Claude Code:

claude mcp add fetch -- kairoseki run --name fetch -- uvx mcp-server-fetch

Restart your client and check that the server connects (with Claude Code: claude mcp get fetch). That's it.

Testing with @modelcontextprotocol/server-filesystem? It replaces the directories you pass on its command line with the client's roots. Claude Code sends the project directory, so the server will serve that folder, not the one in your config.

4. Protect Claude Code's built-in tools too

Claude Code's own Bash, WebFetch, WebSearch, Read and Grep never go through MCP. Kairoseki covers them with hooks, in the same session as your wrapped servers:

kairoseki hooks install            # ~/.claude/settings.json (--scope project|local for one project)
kairoseki hooks uninstall

A secret seen anywhere in the session is denied in any URL or command, even encoded. A sink after untrusted content and private data gets Claude Code's own permission prompt. Hooks only ever answer ask or deny, never allow: they can tighten your permissions, never loosen them. Built-in output can't be rewritten, so redaction stays MCP-only.

5. Try to break it

kairoseki attack                        # grade your current policy
kairoseki attack --badge kairoseki.svg  # and get a README badge
kairoseki scan --share card.svg         # a shareable report card of your setup (counts only, no paths)

MCP Risk Index

Every week, a workflow scans the servers of the official MCP registry that start without credentials, and publishes the MCP Risk Index: tools by trifecta leg, poisoned descriptions, and tool definitions that changed since the last scan (same version + changed definition = possible rug pull). Labels are heuristics: a flag means "worth a look", not "malicious". Build it yourself with uv run python scripts/index/build.py --out site (it starts third-party servers: use a disposable machine).

Building your own agent? Use it as a library

Guard puts the same engine around the Python tools of any framework. Calls are decided like MCP calls, results update the taint and get secrets redacted. The wrapper keeps the function's name, docstring and signature, so it goes under your framework's decorator:

from claude_agent_sdk import tool
from kairoseki import Guard, KairosekiBlocked

guard = Guard()   # or Guard(on_ask=lambda tool, decision: input(f"allow {tool}? ") == "y")

@tool("send_email", "Send an email", {"to": str, "body": str})
@guard.tool()     # labels come from the name and docstring, or pass labels={"sink"}
async def send_email(args): ...

A denied call raises KairosekiBlocked and never runs. Frameworks that replace tool errors with a generic "please try again" (the OpenAI Agents SDK) should get @function_tool(failure_error_function=guard.tool_error), so the model is told why and not to retry. An ask goes to on_ask, or to your phone with Den Den Mushi, or is refused. The Guard also sets KAIROSEKI_SESSION, so MCP servers your agent starts through kairoseki run share its taint.

GitHub Action

Scan the .mcp.json your repo ships, or, if you maintain an MCP server, check on every PR that none of your tool descriptions reads like a prompt injection:

- uses: AnthonyRiveraI/kairoseki@v0.2.0
  with:
    command: node dist/index.js   # your server; leave empty to scan .mcp.json instead
    fail-on: F,D                  # F = poisoned tool, D = lethal trifecta through an unprotected server

The job summary lists every tool by trifecta leg, and kairoseki-card.svg is written for your README. The action starts the servers it scans, so only point it at commands you trust.

How decisions are made

flowchart LR
    A[tool call] --> B{denied by policy,<br/>poisoned or rug-pulled?}
    B -- yes --> X[⛔ deny]
    B -- no --> C{arguments contain a<br/>secret seen this session?}
    C -- yes --> X
    C -- no --> D{session saw untrusted content<br/>AND private data<br/>AND this tool is a sink?}
    D -- yes --> Q[✋ ask the user]
    D -- no --> E{untrusted content seen AND private data<br/>flows into an unclassified tool?}
    E -- yes --> Q
    E -- no --> OK[✅ forward to the server]
    OK --> R[result: sanitize, redact,<br/>fingerprint secrets, update taint]

When Kairoseki asks:

• In-client prompt. If your client supports MCP elicitation, you get an "Allow this call once?" form. Kairoseki sends elicitation/create in the handshake era and an input_required result (SEP-2322) in the 2026-07-28 era.
• 🐌 Your phone (Den Den Mushi). With a denden: section in your policy, Kairoseki rings the free ntfy app with Approve / Deny buttons and waits for your tap: handy for agents running while you're away. Only the server, tool and reason are sent, never the arguments. Set it up with kairoseki denden setup, try it with kairoseki denden test.
• Terminal. Otherwise the agent gets a clear refusal with an id. Run kairoseki approve K-1A2B3C, then ask the agent to retry. Approvals are single-use, bound to the exact arguments, and expire after 10 minutes.

Learn more in docs/how-it-works.md.

Policy

kairoseki init   # writes a commented kairoseki.yaml

mode: balanced
redact:
  secrets: true
  pii: false
servers:
  github:
    tools:
      create_or_update_file: [sink, destructive]  # explicit labels replace the heuristics
    allow: [search_repositories]                  # never ask (redaction still applies)
    deny: [delete_repository]                     # always block

Kairoseki looks for --policy, then $KAIROSEKI_POLICY, then ./kairoseki.yaml, then ~/.kairoseki/kairoseki.yaml.

Other commands

kairoseki log             # recent decisions, redactions and detections
kairoseki status          # protected vs unprotected servers, and live sessions (--all for ended ones)
kairoseki session --explain  # which session this process joins, and why
kairoseki approve         # list pending approvals
kairoseki pins list       # servers whose tools changed since you pinned them
kairoseki pins approve github

Evals

Besides the attack lab, evals/ scores each piece against labeled data, with thresholds set before the first run (uv run python evals/run.py, also in CI):

The 0% is the point: no pattern list catches a well-written injection, which is why Kairoseki's guarantee comes from data flow (the trifecta rule and secret fingerprints), not from recognizing attacks. Paraphrased attacks in the lab are still blocked.

How it compares

➖ = depends on the product. Kairoseki borrows trust-on-first-use pinning and ANSI sanitization from Trail of Bits' excellent mcp-context-protector. The two are complementary.

Limitations (please read)

• It sees MCP traffic, plus Claude Code's built-in tools through hooks. Other clients' built-in tools (Cursor, Gemini CLI...) are not covered yet. Bash is labeled by command name, so a network call hidden inside a script file isn't seen as a sink: pair Kairoseki with your client's permission rules.
• Labels are heuristics. Tool names and descriptions are read as verb + object (get_issue, send_email). They can be wrong, and the policy lets you fix them. Server annotations can only add risk, never remove it.
• Taint is per session and coarse on purpose. Once untrusted content is in the context, Kairoseki assumes it may have influenced everything after it. That is what makes it robust, and it is why strict mode asks more often.
• Secret fingerprints are exact matching. They catch a secret copied whole, base64/hex/URL-encoded, reversed, or split into pieces of 12+ characters, but not one interleaved character by character or run through a custom cipher. The lethal-trifecta rule is the safety net that does not need to recognize the data, so be careful with monitor mode and policy allow: entries, which turn it off.
• Remote servers go through mcp-remote. kairoseki wrap --remote bridges Streamable HTTP and SSE servers to stdio with it (Node.js required), and mcp-remote then handles their OAuth login.
• It is not a sandbox. A malicious server binary can still do anything your user account can. Kairoseki protects against malicious content, not malicious code.

Roadmap

• Streamable HTTP transport
• OpenTelemetry export of decisions
• More attack scenarios. Propose one!

Contributing

The most valuable contribution is a new attack scenario: a real write-up turned into a replayable test. See CONTRIBUTING.md. Found a bypass? Please report it privately.

License

MIT © Anthony Rivera