Kitsune MCP

---

Kitsune es un proxy MCP en tiempo de ejecución: una puerta de enlace siempre activa que tu agente usa para llegar al resto del ecosistema. search encuentra un servidor en 7 registros. shapeshift(id) monta sus herramientas en el turno actual. shapeshift() las elimina. Sin editar configuración. Sin reiniciar el cliente.

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

Instala para alcance y ejecución en vivo — no para ahorrar tokens. La Búsqueda de Herramientas Nativa ya difiere esquemas para servidores que has configurado. Kitsune cubre lo que la Búsqueda de Herramientas no puede: servidores que nunca configuraste, servidores que estás escribiendo ahora mismo, y paquetes comunitarios que quieres probar sin conectarlos a mcp.json para siempre.

	Bucle	Por qué gana
REPL MCP	editar → reload → call	Itera en tu propio servidor sin matar la sesión
Alcance de larga cola	search → shapeshift → call	Casos únicos y APIs oscuras sin preinstalación
Prueba-antes-de-confiar	confirm=True + jaula Docker activada por defecto + pines TOFU	Catálogo comunitario sin instalaciones siempre activas a ciegas

Usa Kitsune cuando…	Omítelo cuando…
Estás construyendo un MCP y necesitas un bucle de edición/recarga	Solo necesitas 1–3 servidores de confianza (configúralos de forma nativa)
Una tarea necesita un servidor que no está en tu configuración	Cada turno usa el mismo servidor (mantenlo siempre activo)
Adivinar banderas de CLI en una API de larga cola es demasiado arriesgado	Quieres tokens más baratos — el mínimo es ~1,774 tokens/turno, aditivo en clientes modernos
Quieres evaluar código MCP comunitario de forma segura	Administración de producción no supervisada / facturación / claves de seguridad (Seguridad)
Estás consolidando una configuración MCP abarrotada (GATEWAY)	Necesitas la primera llamada en menos de un segundo (montaje en frío ~1–15s — prewarm o siempre activo)

Flujos de alto riesgo trabajados (IAM, IR, auditorías): examples/scenarios/. El argumento de precisión CLI vs MCP también vive allí — versión corta: los modelos aciertan comandos CLI comunes y fallan en la larga cola; Kitsune monta esquemas solo mientras los necesitas.

---

Contenido

• Instalación
• Inicio rápido
• Desarrollar un servidor MCP en vivo
• Cómo funciona
• Referencia de herramientas
• Fuentes de servidores
• Modelo de seguridad
• GATEWAY: consolida servidores siempre activos
• Rendimiento
• Configuración
• Patrones de montaje
• Para desarrolladores de MCP
• ¿Por qué Kitsune?
• Contribuir

---

Instalación

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)

Requisitos: Python 3.12+ · node/npx para servidores basados en npm · uvx de uv para servidores basados en PyPI · Docker opcional (sandbox)

Añade una vez a la configuración de tu cliente MCP:

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

Cliente	Archivo de configuración
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	~/.claude/mcp.json
Cursor / Windsurf	~/.cursor/mcp.json
Cline / Continue.dev	Configuración de VS Code / ~/.continue/config.json

También funciona con OpenClaw, Zed y cualquier cliente compatible con MCP.

Perfil ligero en reposo: 9 herramientas · ~1,774 tokens/turno (status, search, auth, shapeshift, call, auto, más el trío REPL connect / release / reload) — medido vía python examples/benchmark.py.

---

Inicio rápido

Toma prestado un servidor que nunca configuraste:

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

Comunitario / larga cola (confirmar; enjaulado por defecto):

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()

Alojado (Smithery HTTP — necesita una SMITHERY_API_KEY gratuita):

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

Credenciales a mitad de sesión:

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

De una sola vez — pasa server_hint cuando conoces el id (auto sin él es de mejor esfuerzo y puede fallar):

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

Recorrido completo en vivo: docs/demo-realtime.md.

---

Desarrollar un servidor MCP en vivo

Construir un MCP normalmente significa: editar → reiniciar cliente → perder sesión → volver a probar. Kitsune convierte eso en un REPL MCP en una sola sesión — y connect / release / reload están en el perfil ligero por defecto, así que esto funciona en un pip install simple sin 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") pliega todo el ciclo — matar el proceso obsoleto, iniciar tu código editado, remontar para que el cliente vea los nuevos esquemas — en una sola llamada. También elimina el clásico error: llamar a connect() de nuevo después de una edición sin liberar primero te devuelve el proceso antiguo; reload siempre libera primero.

Los objetivos connect() locales no son de confianza (se aplican confirm / KITSUNE_TRUST). El aislamiento de procesos ≠ sandbox de seguridad — ver Modelo de seguridad. Habilidad complementaria: kitsune-dev.

---

Cómo funciona

shapeshift(server_id) elige un transporte (stdio / HTTP+SSE / WebSocket / Docker), se conecta, obtiene tools/list, y registra cada herramienta como una herramienta FastMCP nativa con el esquema real del servidor. El cliente recibe notifications/tools/list_changed y ve herramientas de primera clase — sin indirección de envoltorio.

shapeshift() sin argumentos desregistra los proxies, cierra la conexión y vuelve a la línea base ligera.

Modelo mental — RAG de esquemas de herramientas: indexa el ecosistema → search recupera candidatos → shapeshift(..., tools=[…]) inyecta solo lo necesario → el agente llama de forma nativa → shapeshift() desaloja.

Fuente	Transporte
npm	npx <package> (local; sandbox Docker opcional)
PyPI	uvx <package> (local; sandbox Docker opcional)
GitHub	npx github:user/repo o uvx --from git+…
Smithery alojado	HTTP + SSE (SMITHERY_API_KEY)
WebSocket	ws:// / wss://
Imagen Docker	docker run … perfil endurecido

---

Referencia de herramientas

Ligero (por defecto)

Herramienta	Firma	Rol
status()	—	Forma actual, pool, escaneo GATEWAY, estadísticas de sesión
search()	query, registry?, compare?	Abanico en 7 registros
auth()	server_or_var, value?	Claves de entorno + flujo de navegador OAuth 2.1 / cierre de sesión
shapeshift()	server_id?, tools=[], …	Montar / desmontar; tools=[…] quirúrgico; confirm=True; enjaulado por defecto (sandbox=False opta por no participar)
call()	tool_name, arguments	Invocar; servidor inferido cuando está montado
auto()	task, server_hint=, arguments=	buscar → montar → llamar (prefiere server_hint)

Forge (KITSUNE_TOOLS=all o kitsune-forge): connect, release, prewarm, inspect, test, bench, compare, craft, run, fetch, setup, skill, shiftback, … — ver Para desarrolladores de MCP.

---

Fuentes de servidores

Registro	Autenticación	registry=
modelcontextprotocol/servers	—	official
registry.modelcontextprotocol.io	—	mcpregistry
Glama	—	glama
npm	—	npm
PyPI	—	pypi
GitHub	—	github:owner/repo
Smithery	Clave API gratuita	smithery

search() se abanica en registros sin autenticación por defecto. Añade SMITHERY_API_KEY para servidores HTTP alojados (sin instalación local).

---

Modelo de seguridad

Alcanzar 130k servidores comunitarios solo funciona si el código desconocido puede estar contenido. Consentimiento, sandbox y pines son características del producto — no notas al pie.

Controles principales

• confirm=True (o KITSUNE_TRUST) antes de montajes comunitarios / locales
• Los montajes comunitarios npm/PyPI se enjaulan en Docker endurecido por defecto (cuando Docker está presente); sandbox=False o KITSUNE_SANDBOX=off opta por no participar, sandbox=True lo fuerza, KITSUNE_SANDBOX=all enjaula cada montaje local
• Pines TOFU en ~/.kitsune/pins.json — publicaciones maliciosas posteriores no reemplazan silenciosamente lo que ya ejecutaste

Contra qué protege

1. Código no verificado sin consentimiento

Nivel	Fuentes	Al montar
Alto	official	se ejecuta directamente
Medio	mcpregistry, glama, smithery	se ejecuta directamente
Comunitario	npm, pypi, github, connect() local	requiere confirm=True

KITSUNE_TRUST=community renuncia a la puerta; status() advierte cuando esa anulación está activa.

confirm=True no es un límite de aprobación humana. El modelo puede establecerlo. La aprobación real pertenece a la interfaz de aprobación de herramientas de tu cliente.

2. Inyección de shell al iniciar. Los comandos de instalación están validados (sin & ; | $ \ \n / ../) y se lanzan con create_subprocess_exec — sin shell. Verifica la línea de lanzamiento, no lo que el paquete hace una vez en ejecución.

3. SSRF. fetch() y el HTTP del registro son solo HTTPS; hosts privados/de bucle local/no globales bloqueados; cada salto de redirección se revalida (KITSUNE_ALLOW_LOCAL_FETCH=1 para optar por no participar).

4. Exposición de credenciales. ~/.kitsune/.env y oauth/ en modo 0600; OAuth 2.1 + PKCE S256 + DCR (RFC 7591); advertencias de credenciales faltantes antes de las llamadas; auth(id, "logout") borra tokens (RFC 7009 donde esté disponible).

5. Sandbox Docker para servidores locales no confiables — activado por defecto. Los montajes comunitarios npm/pypi/github (y las rutas de ejecución auto()/call()/run()) se enjaulan automáticamente cuando Docker está en PATH; sin FS de host, --cap-drop ALL, rootfs de solo lectura, límites de RAM/PID. Las variables de entorno de credenciales se reenvían por nombre solamente (docker -e KEY) — nunca en argv, ps, o la clave del pool. El primer montaje en sandbox descarga node:22-slim / uv:python3.13-bookworm-slim. De mejor esfuerzo: sin Docker → se ejecuta sin jaula con un aviso (un sandbox=True explícito falla de forma dura en su lugar). Opta por no participar por llamada con sandbox=False o por sesión con KITSUNE_SANDBOX=off. Los servidores de tipo sistema de archivos necesitan rutas de host y no encajan en el sandbox.

Lo que NO hace

• Cage necesita Docker + fuentes confiables opt-in. Los mounts de la comunidad activan cage por defecto solo cuando Docker está presente; sin él (o con sandbox=False/KITSUNE_SANDBOX=off, o para fuentes de confianza media/alta) el stdio local se ejecuta como tu usuario — FS completo, red, entorno heredado. El aislamiento de procesos no es un límite de seguridad.
• Docker ≠ límite del kernel. Los flags endurecidos atenúan escaladas / fork bombs / manipulación de FS; no son una garantía contra escapes de contenedor. Sin non-root / --network none por defecto (la mayoría de los servidores necesitan egress).
• TOFU ≠ pin de digest. Fija una versión, no un hash de contenido. github: / git+ / comandos connect() escritos a mano no están fijados. Alta garantía: fija por digest o vendor.
• Herramientas primero. El proxy de recursos/prompts es más limitado (los URI templates se omiten; la ruta HTTP difiere). "Cualquier servidor" significa ejecución de herramientas.

Conclusión: sólido para uso supervisado de desarrolladores y personal. No lo ejecutes sin supervisión con credenciales de administración de producción, facturación o seguridad en modo local predeterminado. Mantén Docker instalado para que el cage predeterminado se active, y prefiere aprobación del cliente para paquetes no confiables.

Mira los guards en vivo: docs/demo-realtime.md.

---

GATEWAY: consolida servidores siempre activos

Opcional. Mantén los controladores diarios (GitHub, filesystem, …) nativos si prefieres. Cuando una configuración está saturada, status() marca otros servidores siempre activos para que puedas colapsar a una sola entrada de Kitsune y alcanzarlos vía shapeshift:

GATEWAY
  ⚠  1 other server(s) active in claude-desktop (~8 extra tools in context)
     Run setup() to harvest their credentials and reduce bloat

setup()  # preview
setup(action="harvest")  # keys → ~/.kitsune/.env (non-destructive)
setup(action="absorb")  # register for shapeshift()
setup(project=True)  # project mcp.json with only Kitsune

Nunca modifica configuraciones existentes sin confirmación explícita. (setup es forge-profile.)

---

Rendimiento

Latencia de conexión (lo que sientes)

Re-adjuntar del pool cálido dentro de una sesión: 0 ms.

Transporte	Inicio en frío	Cálido
HTTP / Smithery	0–1.4 s	0.0 s
npx local	1.7–6.3 s	0.0 s
uvx local	1.0–5.2 s	0.0 s

Usa prewarm (forge) cuando sepas que necesitarás un servidor pronto.

Sobrecarga de tokens (secundaria)

Real vs siempre activos completamente montados o clientes sin Tool Search. En Claude Code 2.1.7+ con diferimiento nativo, esto no es mayormente una ventaja específica de Kitsune. El pitch del producto es alcance + REPL arriba — no esta tabla.

Cada cifra de Kitsune incluye el piso de ~1,774. Reproduce: python examples/benchmark.py. Metodología: docs/benchmarks.md.

Servidor	Siempre activo	Quirúrgico + piso	vs siempre activo
mcp-server-time	261	~2,035	siempre activo más barato ¹
mcp-server-git	1,242	~2,084	siempre activo más barato ¹
server-memory	2,615	~2,354	10%
server-filesystem	3,207	~2,464	23%
brave	3,612	~2,224	38%
server-github	4,229	~2,074	51%
notion-hosted	13,707	~3,724	73%

¹ Punto de equilibrio: Kitsune se amortiza con más de un servidor mediano, o dos o más pequeños compartiendo el único piso. Stack multi-servidor (GitHub+fs+git → suite Notion): ~72–85% vs siempre activos completamente montados — misma advertencia que arriba.

Menos herramientas visibles también ayuda a la fiabilidad de selección (Gorilla / ToolBench); en clientes modernos, Tool Search entrega gran parte de ese enfoque para servidores configurados. Benchmark de precisión específico de Kitsune: aún no — contribuciones bienvenidas.

---

Configuración

Env y .env

Se relee en cada shapeshift / call — agrega claves a mitad de sesión, sin reinicio.

Orden de búsqueda: CWD/.env → ~/.env → ~/.kitsune/.env (el último gana).

auth("BRAVE_API_KEY", "sk-...")    # → ~/.kitsune/.env

Superficie de herramientas

{ "env": { "KITSUNE_TOOLS": "shapeshift,call,auth" } }   # subset
{ "env": { "KITSUNE_TOOLS": "all" } }                    # forge

Directorio de estado

~/.kitsune/ predeterminado (credenciales, pins, OAuth, sesión). Reubica con KITSUNE_HOME=/tmp/kitsune-iso.

Política de sandbox / confianza

KITSUNE_SANDBOX=community   # Docker-cage community npm/PyPI mounts
KITSUNE_SANDBOX=all         # cage every local mount
KITSUNE_TRUST=community     # waive confirm gate (status warns)
KITSUNE_REPIN=1             # adopt newer pinned version

Smithery

{ "env": { "SMITHERY_API_KEY": "your-key" } }

Clave gratuita: smithery.ai/account/api-keys. Sin ella, npm / PyPI / oficial / GitHub siguen funcionando.

---

Patrones de montaje

Cambia de forma a mitad de sesión — toma solo la porción que necesites:

# Research
shapeshift("brave", tools=["brave_web_search"])
shapeshift("mcp-server-fetch")
shapeshift("@modelcontextprotocol/server-memory", tools=["read_graph", "search_nodes"])

# Code
shapeshift(
    "@modelcontextprotocol/server-filesystem",
    tools=["read_file", "write_file", "edit_file"],
    server_args=["/path/to/project"],
)
shapeshift("mcp-server-git", tools=["git_status", "git_diff", "git_log"])

# Notes
shapeshift("notion-hosted", tools=["notion-search", "notion-append-block-children"])
shapeshift("@modelcontextprotocol/server-memory", tools=["add_memory", "search_nodes"])

shapeshift()  # always drop when the task is done

---

Para desarrolladores de MCP

{ "command": "kitsune-mcp", "env": { "KITSUNE_TOOLS": "all" } }

Herramienta	Rol
connect / release / prewarm	REPL de MCP + pool cálido
inspect(server_id)	Schemas, verificación de credenciales en vivo, costo medido
test(server_id)	Puntaje de calidad 0–100
bench(server_id, tool, args)	Latencia p50 / p95 / min / max
compare(query)	Comparación lado a lado de costo, herramientas, confianza, credenciales
craft(name, description, params, url)	Registra una herramienta viva respaldada por HTTP

Prueba dentro de sesiones reales de Claude / Cursor — no solo una UI de inspector. Habilidades complementarias: kitsune-dev, kitsune-improve.

---

¿Por qué Kitsune?

En el folclore japonés, el Kitsune (狐) es conocido por lo que puede llegar a ser: tomar prestada una forma, usar ese poder, desecharlo y volver a sí mismo.

Ese es el ciclo del producto — alcanzar, usar, liberar; o editar, recargar, re-probar. Una entrada de configuración. La cola larga a una llamada de distancia. Sesión intacta.

shapeshift() es un montaje literal a mitad de sesión, no una metáfora. Ventajas duraderas: alcance, desarrollo en vivo, probar-antes-de-confiar contenido — no una factura de tokens más pequeña en clientes que ya difieren schemas.

No soy japonés, y uso este nombre con el máximo respeto por la mitología y cultura de la que proviene. El paralelo parecía demasiado preciso para ignorarlo.

---

Contribuciones

make dev     # install with dev dependencies
make test    # pytest
make lint    # ruff

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

---

Licencia MIT · Python 3.12+ · Construido sobre FastMCP