kitsune-mcp
Kitsune is an MCP gateway/REPL that lets an agent discover, mount, call, and hot-reload MCP servers mid-session.
Search 6 MCP registries for servers by capability.
Mount a server’s tools at runtime with
shapeshift, optionally only selected tools.Call tools on mounted servers or ad-hoc one-shot servers.
Use
autoto search, pick a server, infer args, and call in one step.Start a persistent local dev server with
connectand hot-reload it after code edits withreload.Release persistent connections and unmount tools when done.
Manage credentials and OAuth flows with
auth.Inspect runtime state, connections, and token stats with
status.Run community packages in a Docker cage by default, with consent and version-pin safeguards.
Provides web search capabilities through the Brave Search API, allowing AI agents to perform internet searches and retrieve information from the web.
Enables interaction with GitHub repositories and platform features through the GitHub MCP server, allowing AI agents to manage code, repositories, and development workflows.
Provides database and backend service integration through Supabase, allowing AI agents to interact with PostgreSQL databases, authentication, and other Supabase features.
AI agents installing this server (Cline, Claude Code, Cursor, …): follow llms-install.md. No clone or build needed. Add the
uvx kitsune-mcpentry to your MCP settings.
Why
Your agent edits an MCP tool, but the client still runs the old process. Someone has to restart it before the agent can test the fix.
With Kitsune, connect, call and reload are tools. The agent runs the whole loop itself:
connect("uv run my-mcp-server", name="dev") # start your server
shapeshift("dev") # its tools appear in the client
call("summarize", arguments={"url": "https://example.com"})
# … the agent (or you) edits the tool …
reload("dev") # restart on fresh code, remount
call("summarize", arguments={"url": "https://example.com"}) # new code, same sessionNo Docker needed: connect() runs your own server as a plain local process, so the loop stays fast.
It also mounts community servers from 6 registries mid-session. If Docker is installed, community packages run caged.
Try it: hot-reload tutorial · examples/demo-hot-reload/
Related MCP server: mcphub
Install
Claude Code
claude mcp add -s user kitsune -- uvx kitsune-mcpAny other client (Claude Desktop, Cursor, Windsurf, Cline, Zed, …):
{
"mcpServers": {
"kitsune": { "command": "uvx", "args": ["kitsune-mcp"] }
}
}Also on PyPI (pip install kitsune-mcp, then "command": "kitsune-mcp") and npm (npx kitsune-mcp, delegates to uvx).
Requirements: Python 3.12+ · uv · node/npx for npm-based servers · Docker optional: not used for hot-reload, only to cage community servers when installed.
Three things it does
Loop | What you get | |
MCP REPL |
| Iterate on your own server without restarting the client |
Long-tail reach |
| Use a server once without adding it to your config forever |
Try before you trust |
| Run community npm/PyPI code contained, not as your user |
Borrow a server you never configured
search("web scraping")
shapeshift("firecrawl", tools=["scrape_url"]) # mount one tool, not the whole server
call("scrape_url", arguments={"url": "https://example.com"})
shapeshift() # drop it, session stays upTry a community package, caged
search("pdf", registry="glama")
shapeshift("mcp-pdf-tools", confirm=True) # npm/PyPI run in hardened Docker when available
call("extract_text", arguments={"path": "report.pdf"})
shapeshift()Add credentials mid-session
auth("BRAVE_API_KEY", "sk-...") # saved to ~/.kitsune/.env, no restart
shapeshift("brave", tools=["brave_web_search"])Full live walkthrough: docs/demo-realtime.md.
When to use it, when not to
Use Kitsune when… | Skip it when… |
You're building an MCP server and want an edit/reload loop | You only use 1–3 trusted servers (configure them natively) |
A task needs a server that isn't in your config | Every turn hits the same server (keep it always-on) |
You want to evaluate community MCP code without installing it for good | You want lower token use: modern clients already defer tool schemas, so most configured servers cost little up front |
Your MCP config is crowded (GATEWAY) | You need a sub-second first call (cold mount takes ~1–15 s) |
How it works
shapeshift(server_id) picks a transport (stdio, HTTP+SSE, WebSocket, Docker), connects, reads tools/list, and registers each tool as a native tool with the server's real schema. The client receives notifications/tools/list_changed and sees first-class tools, with no wrapper in between. shapeshift() with no argument removes them and closes the connection.
search() covers the official servers repo, the MCP Registry, Glama, npm, PyPI, GitHub (github:owner/repo). Hosted servers are reached at their own https:// URL.
Tools
Default profile: 9 tools. Standing cost: ~1,774 tokens/turn on clients that load every tool schema up front (measured with python examples/benchmark.py); ~70 tokens/turn on Claude Code with Tool Search, where schemas load only on first use (measured on Claude Code 2.1.319, 2026-11-06).
Tool | Role |
| Start a persistent local server, e.g. the one you're developing |
| Release, restart on fresh code, remount, in one call |
| Stop a persistent server |
| Search 6 registries |
| Mount a server's tools (all or a subset); no argument drops them |
| Call a tool; the server is inferred when mounted |
| Set an env key or run an OAuth 2.1 browser flow |
| Search, mount and call in one step |
| Current form, connection pool, session stats |
KITSUNE_TOOLS=all (or the kitsune-forge command) adds developer tools: inspect (schemas, credential check, token cost), test (quality score 0–100), bench (p50/p95 latency), compare, prewarm, craft, setup, and more. See docs/tools.md. Companion skills for Claude Code: kitsune-dev, kitsune-improve.
Safety, in short
Community sources need consent. npm, PyPI and GitHub servers require
confirm=True. The model can set that flag itself, so real approval belongs in your client's tool-approval UI.connect()runs the command it is given, as your user, with no consent gate and no cage. It is meant for your own code. Approveconnectcalls in your client before the agent runs them.Community packages run in a Docker cage by default when Docker is installed: no host filesystem,
--cap-drop ALL, read-only root, memory and PID limits. Credentials are passed by name, never in argv.Version pins (TOFU). A later malicious publish doesn't silently replace a version you already ran.
Opt-in action guard. A
~/.kitsune/policy.jsonchecks every downstream call against allow/ask/deny rules, path roots and a host allowlist.askgoes to you through MCP elicitation.Install commands are validated and launched without a shell.
fetch()blocks private hosts and re-checks every redirect.
Don't run it unattended with production admin, billing or security credentials. The full model, including what it does not protect against: docs/safety.md.
More
Configuration: env and
.envlookup, tool profiles, sandbox and trust settings, GATEWAY, mount patternsPerformance: cold/warm latency and token cost compared with always-on servers
Transports · Compatibility · Agent patterns · Worked scenarios
Why "Kitsune"?
In Japanese folklore the kitsune (狐) is known for what it can become: it borrows a form, uses that power, casts it off and returns to itself. That is the product loop.
I am not Japanese, and I use this name with the highest respect for the mythology and culture it comes from. The parallel felt too precise to ignore.
Contributing
make dev # install with dev dependencies
make test # pytest
make lint # ruffIssues and PRs welcome: github.com/kaiser-data/kitsune-mcp · CHANGELOG.md
MIT License · Python 3.12+ · Built on FastMCP
Available Tools
9 toolsauthA
Check or set credentials. ALL_CAPS = env var; server-id = creds check or OAuth.
auth('GITHUB_TOKEN', 'ghp_...') # save env var auth('GITHUB_TOKEN') # check if set auth('server-id') # show creds needed / run OAuth auth('server-id', 'logout') # revoke OAuth tokens
Inputs: server_id_or_var (required), value. Returns: result
autoB
search → pick server → infer args → call. Use when you don't know which server to use.
auto('what time in Tokyo') auto('list issues on acme/api', server_hint='github')
Inputs: task (required), keys, arguments, tool_name, +1 more. Returns: result
callA
Invoke a tool on an MCP server. Returns the tool's response as text.
Routes through the warm pooled transport when a server is shapeshifted; otherwise spins up a transient transport for the given server_id. Records the call in session stats. Long responses (HTML, large outputs) are truncated with a continuation note.
Use when: the tool name and target server are known. Avoid when: discovery is needed — auto() does search → pick → call in one step.
call('get_current_time', arguments={'timezone': 'UTC'}) # after shapeshift call('list_directory', '@mcp/server-fs', {'path': '/tmp'}) # ad-hoc one-shot
Inputs: tool_name (required), config, arguments, server_id. Returns: result
connectC
Start a persistent server. command: server_id or shell cmd (e.g. 'uvx voice-mode'). name: alias for release().
Inputs: command (required), name, timeout, inherit_stderr. Returns: result
releaseB
Kill a persistent connection by name.
Inputs: name (required). Returns: result
reloadA
Reload a persistent connection after editing its code — the MCP REPL in one call.
reload('dev') # release the stale process, start fresh code, remount live
Replaces the manual release() + connect() + shapeshift() cycle and removes the
"connect() handed back the old process" footgun (it always releases first).
name is the alias you gave connect().
Inputs: name (required). Returns: result
searchA
Discover MCP servers across registries — the entry point to mounting.
Returns a ranked list of server_ids with name, description, source, and credential-readiness status. Records discovered servers in session so status() can summarize them. Reports per-registry failures inline rather than failing the whole call.
Use when: you need to find a server matching a capability before mounting. Avoid when: the server_id is already known — go straight to shapeshift() or inspect().
search('web search') # find candidates search('postgres', compare=True) # side-by-side token-cost table search('vector db', registry='official')
registry: all|official|mcpregistry|glama|npm|pypi
Inputs: query (required), limit, compare, registry. Returns: result
shapeshiftA
Mount an MCP server's tools at runtime. Empty server_id unmounts.
shapeshift('mcp-server-time') # mount (community sources cage by default) shapeshift('id', tools=['only_this']) # lean — mount only listed tools shapeshift('id', sandbox=False) # opt out of the default Docker cage shapeshift('id', sandbox=True) # force the cage (hard-fail if no Docker) shapeshift() # unmount + kill process
sandbox: None (default) cages low-trust npm/PyPI/github sources in Docker when it's available (best-effort — runs uncaged with a nudge if not); True forces the cage; False opts out. source: auto|local|official. confirm=True for community sources.
Inputs: keep, tools, source, confirm, +3 more. Returns: result
statusA
Show Kitsune runtime state: providers, current form, connections, token stats.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Core purposes are mostly distinct: search finds servers, auth handles credentials, call invokes tools, and status/release/reload manage runtime state. However connect vs shapeshift both begin server/tool availability, and auto overlaps with the search+call path; the descriptions mostly resolve these boundaries but not perfectly.
All tool names are concise lowercase single words, which is visually consistent and readable. Most are action verbs, but status/auth/auto are noun or abbreviated forms and shapeshift is metaphorical, so the set does not follow a strict verb_noun convention.
Nine tools is well within the appropriate range for an MCP runtime manager, and each maps to a meaningful operation covering discovery, credentials, mounting/calling, lifecycle, and status. The surface does not feel bloated or arbitrarily large.
The lifecycle and call paths are mostly covered, but search's description explicitly points to inspect(), which is absent from the tool surface. Agents needing to inspect server capabilities or tool signatures before a manual call may be forced to rely on auto/general inference, which is a notable gap.
Maintenance
Related MCP Connectors
MCP registry: 138k servers crawled, handshake-validated, reliability-scored. 744 production-safe.
Search and discover 25,000+ MCP servers across all major registries. Connect and pay autonomously.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
Related MCP Servers
- AlicenseAqualityDmaintenanceA server that implements the Model Context Protocol for managing dynamic forms, allowing users to create, retrieve, and handle responses for web forms via the @dynamicfrm/js library.4ISC
- AlicenseNot gradedqualityAmaintenanceA unified hub for centrally managing and dynamically orchestrating multiple MCP servers/APIs into separate endpoints with flexible routing strategies.2,715Apache 2.0
- -
- AlicenseCqualityDmaintenanceEnables academic research through paper search across multiple databases (IACR, CryptoBib, Crossref, Google Scholar), PDF processing, and GitHub repository browsing. Features modular architecture with FastMCP-based proxy server routing to specialized academic tools.751 PyPI2MIT