Skip to main content
Glama

AI agents installing this server (Cline, Claude Code, Cursor, …): follow llms-install.md. No clone or build needed. Add the uvx kitsune-mcp entry to your MCP settings.

GitHub stars PyPI npm PyPI downloads PyPI monthly npm monthly MCP Registry Python CI Coverage OpenSSF Scorecard License: MIT Glama MCP Market Listed in Awesome MCP Servers


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 session

No 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-mcp

Any 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

connect → shapeshift → edit → reload → call

Iterate on your own server without restarting the client

Long-tail reach

search → shapeshift → call → shapeshift()

Use a server once without adding it to your config forever

Try before you trust

confirm=True + Docker cage + version pins

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 up

Try 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

connect(command, name)

Start a persistent local server, e.g. the one you're developing

reload(name)

Release, restart on fresh code, remount, in one call

release(name)

Stop a persistent server

search(query, registry?)

Search 6 registries

shapeshift(server_id?, tools=[…])

Mount a server's tools (all or a subset); no argument drops them

call(tool_name, arguments)

Call a tool; the server is inferred when mounted

auth(var_or_server, value?)

Set an env key or run an OAuth 2.1 browser flow

auto(task, server_hint=)

Search, mount and call in one step

status()

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. Approve connect calls 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.json checks every downstream call against allow/ask/deny rules, path roots and a host allowlist. ask goes 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

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    # ruff

Issues and PRs welcome: github.com/kaiser-data/kitsune-mcp · CHANGELOG.md


MIT License · Python 3.12+ · Built on FastMCP

Available Tools

9 tools
authA

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

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

    A3.6/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      4
      ISC
    • A
      license
      C
      quality
      D
      maintenance
      Enables 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.
      7
      51 PyPI
      2
      MIT