🦊 Kitsune MCP

The agent harness for MCP.
One config entry. Borrow any of 130,000+ servers mid-session — develop live, reach the long tail, try community code contained — then shift back.
Session survives.

Kitsune is a runtime MCP proxy: one always-on gateway your agent uses to reach the rest of the ecosystem. search finds a server across 7 registries. shapeshift(id) mounts its tools in the current turn. shapeshift() drops them. No config edit. No client restart.

search → shapeshift → call → shapeshift()       # reach, use, release
connect → shapeshift → edit → reload → call     # MCP REPL (default install)

Install for reach and live execution — not for token savings. Native Tool Search already defers schemas for servers you've configured. Kitsune covers what Tool Search cannot: servers you've never set up, servers you're writing right now, and community packages you want to try without wiring them into mcp.json forever.

Worked high-stakes flows (IAM, IR, audits): examples/scenarios/. CLI vs MCP accuracy argument lives there too — short version: models nail common CLI commands and fail on the long tail; Kitsune mounts schemas only while you need them.

Contents

• Installation
• Quick start
• Developing an MCP server live
• How it works
• Tool reference
• Server sources
• Safety model
• GATEWAY: consolidate always-on servers
• Performance
• Configuration
• Mount patterns
• For MCP developers
• Why Kitsune?
• Contributing

Installation

pip install kitsune-mcp      # recommended
# or
uvx kitsune-mcp              # isolated env via uv, no venv setup
# or
npx kitsune-mcp              # npm (delegates to uvx internally)

Requirements: Python 3.12+ · node/npx for npm-based servers · uvx from uv for PyPI-based servers · Docker optional (sandbox)

Add once to your MCP client config:

{
  "mcpServers": {
    "kitsune": { "command": "kitsune-mcp" }
  }
}

Also works with OpenClaw, Zed, and any MCP-compatible client.

Lean profile at rest: 9 tools · ~1,774 tokens/turn (status, search, auth, shapeshift, call, auto, plus the connect / release / reload REPL trio) — measured via python examples/benchmark.py.

Quick start

Borrow a server you never configured:

search("web scraping")
shapeshift("firecrawl", tools=["scrape_url"])  # surgical: one tool, not the whole surface
call("scrape_url", arguments={"url": "https://example.com"})
shapeshift()  # drop form — session stays up

Community / long-tail (confirm; caged by default):

search("pdf", registry="glama")
shapeshift("mcp-pdf-tools", confirm=True)  # npm/PyPI caged in Docker by default (when available)
call("extract_text", arguments={"path": "report.pdf"})
shapeshift("mcp-pdf-tools", confirm=True, sandbox=False)  # opt out of the cage
shapeshift()

Hosted (Smithery HTTP — needs a free SMITHERY_API_KEY):

search("exa", registry="smithery")
shapeshift("exa")
call("web_search_exa", arguments={"query": "MCP registry growth 2026"})
shapeshift()

Credentials mid-session:

auth("BRAVE_API_KEY", "sk-...")
shapeshift("brave", tools=["brave_web_search"])
call("brave_web_search", arguments={"query": "MCP protocol 2026"})
shapeshift()

One-shot — pass server_hint when you know the id (auto without it is best-effort and can misfire):

auto("current time in Tokyo", server_hint="mcp-server-time")

Full live walkthrough: docs/demo-realtime.md.

Developing an MCP server live

Building an MCP normally means: edit → restart client → lose session → re-test. Kitsune turns that into an MCP REPL in one session — and connect / release / reload are in the default lean profile, so this works on a plain pip install with no KITSUNE_TOOLS=all.

connect("uvx --from . my-mcp-server", name="dev")  # start child process
shapeshift("dev")  # mount tools → client sees them
call("summarize", arguments={"url": "https://example.com"})

# … edit the tool in your editor …

reload("dev")  # release → restart fresh code → remount, one call
call("summarize", arguments={"url": "https://example.com"})

reload("dev") folds the whole cycle — kill the stale process, start your edited code, remount so the client sees the new schemas — into a single call. It also removes the classic footgun: calling connect() again after an edit without releasing first hands you back the old process; reload always releases first.

Local connect() targets are untrusted (confirm / KITSUNE_TRUST apply). Process isolation ≠ security sandbox — see Safety model. Companion skill: kitsune-dev.

How it works

shapeshift(server_id) picks a transport (stdio / HTTP+SSE / WebSocket / Docker), connects, fetches tools/list, and registers each tool as a native FastMCP tool with the server's real schema. The client gets notifications/tools/list_changed and sees first-class tools — no wrapper indirection.

shapeshift() with no args deregisters proxies, closes the connection, and returns to the lean baseline.

Mental model — tool-schema RAG: index the ecosystem → search retrieves candidates → shapeshift(..., tools=[…]) injects only what's needed → agent calls natively → shapeshift() evicts.

Tool reference

Lean (default)