Kitsune MCP

---

Kitsune é um proxy MCP em tempo de execução: um gateway sempre ativo que seu agente usa para alcançar o resto do ecossistema. search encontra um servidor em 7 registros. shapeshift(id) monta suas ferramentas no turno atual. shapeshift() as remove. Sem edição de configuração. Sem reiniciar o cliente.

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

Instale para alcance e execução ao vivo — não para economizar tokens. A Busca de Ferramentas Nativa já adia esquemas para servidores que você configurou. Kitsune cobre o que a Busca de Ferramentas não consegue: servidores que você nunca configurou, servidores que você está escrevendo agora e pacotes da comunidade que você quer testar sem conectá-los ao mcp.json para sempre.

	Loop	Por que vence
MCP REPL	editar → reload → call	Itere no seu próprio servidor sem matar a sessão
Alcance de cauda longa	search → shapeshift → call	Casos únicos e APIs obscuras sem pré-instalação
Experimente antes de confiar	confirm=True + jaula Docker ativada por padrão + pinos TOFU	Catálogo da comunidade sem instalações sempre ativas às cegas

Use Kitsune quando…	Pule quando…
Você está construindo um MCP e precisa de um loop de edição/recarga	Você só precisa de 1–3 servidores confiáveis (configure-os nativamente)
Uma tarefa precisa de um servidor que não está na sua configuração	Todo turno usa o mesmo servidor (mantenha-o sempre ativo)
Adivinhar flags de CLI em uma API de cauda longa é arriscado demais	Você quer tokens mais baratos — o mínimo é ~1.774 tokens/turno, aditivo em clientes modernos
Você quer avaliar código MCP da comunidade com segurança	Administração de produção não supervisionada/faturamento/chaves de segurança (Segurança)
Você está consolidando uma configuração MCP lotada (GATEWAY)	Você precisa de primeira chamada em menos de um segundo (montagem a frio ~1–15s — prewarm ou sempre ativo)

Fluxos de alto risco trabalhados (IAM, RI, auditorias): examples/scenarios/. O argumento sobre precisão de CLI vs MCP também está lá — versão curta: modelos acertam comandos CLI comuns e falham na cauda longa; Kitsune monta esquemas apenas enquanto você precisa deles.

---

Conteúdo

• Instalação
• Início rápido
• Desenvolvendo um servidor MCP ao vivo
• Como funciona
• Referência de ferramentas
• Fontes de servidores
• Modelo de segurança
• GATEWAY: consolide servidores sempre ativos
• Desempenho
• Configuração
• Padrões de montagem
• Para desenvolvedores MCP
• Por que Kitsune?
• Contribuindo

---

Instalação

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 baseados em npm · uvx do uv para servidores baseados em PyPI · Docker opcional (sandbox)

Adicione uma vez à configuração do seu cliente MCP:

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

Cliente	Arquivo de configuração
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	Configurações do VS Code / ~/.continue/config.json

Também funciona com OpenClaw, Zed e qualquer cliente compatível com MCP.

Perfil enxuto em repouso: 9 ferramentas · ~1.774 tokens/turno (status, search, auth, shapeshift, call, auto, mais o trio REPL connect / release / reload) — medido via python examples/benchmark.py.

---

Início rápido

Pegue emprestado um servidor que você nunca configurou:

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

Comunidade / cauda longa (confirme; em jaula por padrão):

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

Hospedado (Smithery HTTP — precisa de um SMITHERY_API_KEY gratuito):

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

Credenciais no meio da sessão:

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

Única execução — passe server_hint quando souber o id (auto sem ele é melhor esforço e pode falhar):

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

Passo a passo completo ao vivo: docs/demo-realtime.md.

---

Desenvolvendo um servidor MCP ao vivo

Construir um MCP normalmente significa: editar → reiniciar cliente → perder sessão → testar de novo. Kitsune transforma isso em um MCP REPL em uma única sessão — e connect / release / reload estão no perfil enxuto padrão, então isso funciona em um pip install simples sem 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") dobra todo o ciclo — matar o processo obsoleto, iniciar seu código editado, remontar para que o cliente veja os novos esquemas — em uma única chamada. Também remove a armadilha clássica: chamar connect() novamente após uma edição sem liberar primeiro devolve o processo antigo; reload sempre libera primeiro.

Alvos locais connect() não são confiáveis (confirm / KITSUNE_TRUST se aplicam). Isolamento de processo ≠ sandbox de segurança — veja Modelo de segurança. Habilidade complementar: kitsune-dev.

---

Como funciona

shapeshift(server_id) escolhe um transporte (stdio / HTTP+SSE / WebSocket / Docker), conecta, busca tools/list e registra cada ferramenta como uma ferramenta FastMCP nativa com o esquema real do servidor. O cliente recebe notifications/tools/list_changed e vê ferramentas de primeira classe — sem indireção de wrapper.

shapeshift() sem argumentos desregistra proxies, fecha a conexão e retorna à linha de base enxuta.

Modelo mental — RAG de esquema de ferramentas: indexar o ecossistema → search recupera candidatos → shapeshift(..., tools=[…]) injeta apenas o necessário → agente chama nativamente → shapeshift() remove.

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

---

Referência de ferramentas

Enxuto (padrão)

Ferramenta	Assinatura	Função
status()	—	Forma atual, pool, varredura GATEWAY, estatísticas da sessão
search()	query, registry?, compare?	Fan-out em 7 registros
auth()	server_or_var, value?	Chaves de ambiente + fluxo de navegador OAuth 2.1 / logout
shapeshift()	server_id?, tools=[], …	Montar / desmontar; tools=[…] cirúrgico; confirm=True; em jaula por padrão (sandbox=False opta por sair)
call()	tool_name, arguments	Invocar; servidor inferido quando montado
auto()	task, server_hint=, arguments=	buscar → montar → chamar (prefira server_hint)

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

---

Fontes de servidores

Registro	Autenticação	registry=
modelcontextprotocol/servers	—	official
registry.modelcontextprotocol.io	—	mcpregistry
Glama	—	glama
npm	—	npm
PyPI	—	pypi
GitHub	—	github:owner/repo
Smithery	Chave de API gratuita	smithery

search() faz fan-out em registros sem autenticação por padrão. Adicione SMITHERY_API_KEY para servidores HTTP hospedados (sem instalação local).

---

Modelo de segurança

Alcançar 130 mil servidores da comunidade só funciona se código desconhecido puder ser contido. Consentimento, sandbox e pinos são recursos do produto — não notas de rodapé.

Controles principais

• confirm=True (ou KITSUNE_TRUST) antes de montagens da comunidade / locais
• Montagens npm/PyPI da comunidade ficam em jaula Docker endurecida por padrão (quando Docker está presente); sandbox=False ou KITSUNE_SANDBOX=off opta por sair, sandbox=True força, KITSUNE_SANDBOX=all coloca em jaula toda montagem local
• Pinos TOFU em ~/.kitsune/pins.json — publicações maliciosas posteriores não substituem silenciosamente o que você já executou

Contra o que protege

1. Código não verificado sem consentimento

Nível	Fontes	Na montagem
Alto	official	executa diretamente
Médio	mcpregistry, glama, smithery	executa diretamente
Comunidade	npm, pypi, github, local connect()	exige confirm=True

KITSUNE_TRUST=community dispensa a barreira; status() avisa quando essa substituição está ativa.

confirm=True não é um limite de aprovação humana. O modelo pode defini-lo. Aprovação real pertence à UI de aprovação de ferramentas do seu cliente.

2. Injeção de shell na inicialização. Comandos de instalação são validados (sem & ; | $ \ \n / ../) e lançados com create_subprocess_exec — sem shell. Verifica a linha de lançamento, não o que o pacote faz quando em execução.

3. SSRF. fetch() e HTTP de registro são somente HTTPS; hosts privados/loopback/não globais bloqueados; cada salto de redirecionamento é revalidado (KITSUNE_ALLOW_LOCAL_FETCH=1 para optar por sair).

4. Exposição de credenciais. ~/.kitsune/.env e oauth/ no modo 0600; OAuth 2.1 + PKCE S256 + DCR (RFC 7591); avisos de credenciais ausentes antes de chamadas; auth(id, "logout") limpa tokens (RFC 7009 quando disponível).

5. Sandbox Docker para servidores locais não confiáveis — ativado por padrão. Montagens da comunidade npm/pypi/github (e os caminhos de execução auto()/call()/run()) ficam em jaula automaticamente quando Docker está em PATH; sem FS do host, --cap-drop ALL, rootfs somente leitura, limites de RAM/PID. Variáveis de ambiente de credenciais são encaminhadas apenas por nome (docker -e KEY) — nunca em argv, ps ou na chave do pool. Primeira montagem em sandbox puxa node:22-slim / uv:python3.13-bookworm-slim. Melhor esforço: sem Docker → executa sem jaula com um aviso (um sandbox=True explícito falha de forma rígida). Opte por sair por chamada com sandbox=False ou por sessão com KITSUNE_SANDBOX=off. Servidores estilo sistema de arquivos precisam de caminhos do host e não cabem no sandbox.

O que NÃO faz

• Cage precisa de Docker + fontes confiáveis opt-in. A comunidade monta o cage por padrão apenas quando o Docker está presente; sem ele (ou com sandbox=False/KITSUNE_SANDBOX=off, ou para fontes de confiança média/alta) o stdio local roda como seu usuário — FS completo, rede, env herdado. Isolamento de processo ≠ fronteira de segurança.
• Docker ≠ fronteira de kernel. Flags endurecidas reduzem escalonamento / fork bombs / adulteração de FS; não é garantia contra escape de contêiner. Sem non-root padrão / --network none (a maioria dos servidores precisa de egress).
• TOFU ≠ pin de digest. Fixa uma versão, não um hash de conteúdo. github: / git+ / comandos connect() escritos à mão não são fixados. Alta garantia: fixe por digest ou forneça.
• Ferramentas primeiro. Proxy de recursos/prompts é mais restrito (templates de URI ignorados; caminho HTTP difere). "Qualquer servidor" significa execução de ferramentas.

Resumo: forte para uso supervisionado por desenvolvedores e uso pessoal. Não execute sem supervisão com credenciais de admin de produção, cobrança ou segurança no modo local padrão. Mantenha o Docker instalado para que o cage padrão seja ativado, e prefira aprovação do cliente para pacotes não confiáveis.

Veja as proteções ao vivo: docs/demo-realtime.md.

---

GATEWAY: consolide servidores sempre ativos

Opcional. Mantenha os drivers diários (GitHub, filesystem, …) nativos se preferir. Quando uma configuração está cheia, status() sinaliza outros servidores sempre ativos para que você possa colapsar em uma única entrada Kitsune e alcançá-los via 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 configurações existentes sem confirmação explícita. (setup é forge-profile.)

---

Performance

Latência de conexão (o que você sente)

Re-anexação do pool aquecido dentro de uma sessão: 0 ms.

Transporte	Cold start	Aquecido
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

Use prewarm (forge) quando souber que precisará de um servidor em breve.

Overhead de tokens (secundário)

Real vs sempre ativo totalmente montado ou clientes sem Tool Search. No Claude Code 2.1.7+ com adiamento nativo, isso não é majoritariamente uma vantagem específica do Kitsune. O pitch do produto é alcance + REPL acima — não esta tabela.

Cada figura do Kitsune inclui o piso de ~1.774. Reproduza: python examples/benchmark.py. Metodologia: docs/benchmarks.md.

Servidor	Sempre ativo	Cirúrgico + piso	vs sempre ativo
mcp-server-time	261	~2.035	sempre ativo mais barato ¹
mcp-server-git	1.242	~2.084	sempre ativo mais 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%

¹ Ponto de equilíbrio: Kitsune compensa a partir de um servidor médio, ou dois ou mais pequenos compartilhando o piso único. Stack multi-servidor (GitHub+fs+git → suíte Notion): ~72–85% vs sempre ativo totalmente montado — mesma ressalva acima.

Menos ferramentas visíveis também ajuda na confiabilidade de seleção (Gorilla / ToolBench); em clientes modernos, Tool Search entrega muito desse foco para servidores configurados. Benchmark de precisão específico do Kitsune: ainda não — contribuições bem-vindas.

---

Configuração

Env e .env

Relido a cada shapeshift / call — adicione chaves no meio da sessão, sem reiniciar.

Ordem de busca: CWD/.env → ~/.env → ~/.kitsune/.env (o último vence).

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

Superfície de ferramentas

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

Diretório de estado

Padrão ~/.kitsune/ (credenciais, pins, OAuth, sessão). Realoque com KITSUNE_HOME=/tmp/kitsune-iso.

Política de sandbox / confiança

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" } }

Chave gratuita: smithery.ai/account/api-keys. Sem ela, npm / PyPI / oficial / GitHub ainda funcionam.

---

Padrões de montagem

Alterne formas no meio da sessão — pegue apenas a fatia que precisa:

# 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 desenvolvedores MCP

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

Ferramenta	Papel
connect / release / prewarm	MCP REPL + pool aquecido
inspect(server_id)	Schemas, verificação de creds ao vivo, custo medido
test(server_id)	Pontuação de qualidade 0–100
bench(server_id, tool, args)	Latência p50 / p95 / min / max
compare(query)	Custo lado a lado, ferramentas, confiança, creds
craft(name, description, params, url)	Registre uma ferramenta HTTP ao vivo

Teste dentro de sessões reais de Claude / Cursor — não apenas uma UI de inspetor. Habilidades complementares: kitsune-dev, kitsune-improve.

---

Por que Kitsune?

No folclore japonês, a Kitsune (狐) é conhecida pelo que pode se tornar: emprestar uma forma, usar esse poder, descartá-lo, voltar a si mesma.

Esse é o loop do produto — alcance, use, libere; ou edite, recarregue, re-teste. Uma entrada de configuração. Cauda longa a uma chamada de distância. Sessão intacta.

shapeshift() é uma montagem literal no meio da sessão, não uma metáfora. Vantagens duráveis: alcance, desenvolvimento ao vivo, experimentação contida antes de confiar — não uma conta de tokens menor em clientes que já adiam schemas.

Não sou japonês, e uso este nome com o maior respeito pela mitologia e cultura de onde ele vem. O paralelo parecia preciso demais para ignorar.

---

Contribuindo

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

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

---

Licença MIT · Python 3.12+ · Construído em FastMCP