kairoseki 0.1.2

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.

uv tool install git+https://github.com/AnthonyRiveraI/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

Kairoseki is not on PyPI yet, so install it from GitHub:

uv tool install git+https://github.com/AnthonyRiveraI/kairoseki
# or with pipx:
pipx 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 --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. Try to break it

kairoseki attack                        # grade your current policy
kairoseki attack --badge kairoseki.svg  # and get a README badge

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.
• 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

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 only sees MCP traffic. Built-in client tools (for example Claude Code's own Bash or WebFetch) never go through MCP. 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.
• stdio servers only in v0.1. Streamable HTTP servers are on the roadmap.
• 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

• Publish on PyPI (pipx install kairoseki)
• Streamable HTTP transport
• 🐌 Den Den Mushi: Kairoseki calls your phone to approve risky actions
• 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