convez.ai
MCP ServerIntegração & APIsAvançado
amarbel-llc

Moxy

amarbel-llc/moxy

Proxy MCP unificado com caching, moxins e controle de permissões

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que agrega múltiplos servidores MCP filhos em uma única conexão unificada. Oferece cache de resultados, divulgação progressiva com URIs compostas, framework declarativo para criar ferramentas sem código (moxins) e controle granular de permissões por ferramenta.

Instalação

$npx convez-ai amarbel-llc/moxy

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 4 dias
Versão
v0.6.42
Issues abertas
1
Contribuidores
3

Casos de uso

  • Agregar múltiplos servidores MCP em um único ponto de acesso
  • Criar ferramentas MCP declarativas via TOML sem escrever código
  • Controlar permissões granulares por ferramenta (leitura, confirmação, bloqueio)
  • Otimizar janela de contexto com caching e progressive disclosure de outputs grandes
  • Compor resultados entre ferramentas via URIs compostas

Veredito

Moxy é uma solução sofisticada para quem precisa orquestrar múltiplos servidores MCP com controle fino. O suporte a moxins (ferramentas declarativas em TOML) reduz significativamente a curva de entrada para extensibilidade, mas a arquitetura geral é complexa e exige familiaridade com MCP e Go.

README

A tradução para o português deste README ainda está na fila.

moxy

MCP proxy that aggregates multiple child MCP servers into a single unified server.

Overview

Moxy spawns child MCP servers as subprocesses, communicates with them via JSON-RPC over stdio, and presents their tools, resources, and prompts through a single unified MCP server. Child server capabilities are namespaced with a dot separator (e.g. grit.status, chix.build).

Configuration is loaded from a hierarchy of TOML moxyfiles — global (~/.config/moxy/moxyfile), per-directory, and project-local — with later files overriding earlier ones by server name. Moxy also discovers declarative tool configs called moxins from MOXIN_PATH, so you can add MCP tools without writing any Go code.

Why moxy

Traditional MCP servers are standalone programs that each handle their own protocol negotiation, process lifecycle, and output management. Moxy replaces that per-server boilerplate with a shared runtime that provides several features out of the box:

Result caching and progressive disclosure. Tool outputs exceeding the inline-token threshold are streamed into madder (a content-addressable blob store) and replaced with a madder://blobs/<digest> URI plus a head/tail summary. Agents see enough to decide whether the full output matters, and can read the full blob with madder cat <digest> (or via the madder://blobs/{digest} resource) — without blowing up the context window on a 10,000-line git log. Truncation warnings are explicit so agents never mistake partial output for complete output. Moxy expects a .default store at startup; spinclass auto-initializes one per worktree, otherwise run madder init .default from your repo root.

Composable result URIs. The madder://blobs/<digest> URIs are first-class across moxin tools. A folio.read call can take the URI from a previous rg.search result as its file path; a jq.jq call can take one as stdin. Moxy rewrites these to file descriptors at invocation time (piping madder cat <digest> stdout through to the child process), so tools chain without the agent needing to copy data between calls.

Declarative tool authoring. Moxins are TOML files — a manifest plus one file per tool. Each tool file declares its name, description, input schema, command, and args. Moxy handles MCP protocol, argument passing, process invocation, result caching, and permission signaling. No SDK, no boilerplate, no server code.

Permission control. Each moxin tool can declare a perms-request field: always-allow (skip confirmation), each-use (always prompt), or delegate-to-client (let the client decide). This lets read-only tools like folio.read run without interrupting the agent, while destructive tools like grit.push require explicit approval.

Unified discovery. Agents see all tools from all servers through a single MCP connection. Built-in moxy:// resources let agents introspect available servers, tool counts, and full JSON schemas at runtime without additional configuration.

Install

Nix

nix run github:amarbel-llc/moxy

Or add to your flake inputs for the full package with nix-wrapped moxins.

Moxins

A moxin is a directory of TOML files that defines an MCP server without any code. The directory contains a _moxin.toml manifest and one .toml file per tool:

moxins/grit/
  _moxin.toml        # server name, description
  log.toml           # tool: show commit history
  diff.toml          # tool: show changes
  commit.toml        # tool: create a commit
  ...

Each tool file declares its input schema, command, and args. Moxy handles everything else — MCP protocol, argument passing (schema-ordered, then alphabetical), process invocation, result caching, and permission signaling. See moxin(7) for the full authoring guide.

Shipped moxins

The following moxins ship with moxy. Each can be served individually via moxy serve-moxin --name <name> or aggregated through the proxy.

MoxinToolsDescriptionDeps
calendar1Google Calendar: view upcoming events and agendasbun, gws
car5Google Drive: search, list, get, and export filesbun, gws
env5Environment inspection: PATH binaries and env vars—
folio16File I/O. Auto-allows inside CWD, /nix/store, and ~/.claude tree; prompts elsewherejq, coreutils
freud12Past Claude Code session transcriptspython3
get-hubbed31GitHub tools (defaults to current repo; pass repo_owner_name to target a different repo)gh, jq, bun
gmail2Gmail: triage and read messagesbun, gws
grit31Git operations (force-push/hard-reset blocked on main/master)git, jq
gws1Google Workspace: generic API passthroughbun, gws
hamster8Go package documentation via go docgo, bun
jq1Execute jq filters on JSON datajq
just-us-agents6Justfile recipe runnerjust, jq, bun
man4Unix man page reader with section-level progressive disclosurepandoc, mandoc
piers13Google Docs: read, create, edit, and comment on documentsbun, gws
prison1Google Sheets: read spreadsheet databun, gws
rg1Ripgrep code search with structured output modesripgrep
sisyphus10Jira Cloud toolspython3, atlassian-python-api
slip0Google Slides: read and edit presentationsbun, gws

Usage

As a Claude Code plugin

moxy install-claude-plugin

This registers moxy as a Claude Code MCP server plugin. All moxins discovered from MOXIN_PATH are served through the proxy alongside any servers defined in your moxyfile hierarchy.

Serve a single moxin

moxy serve-moxin --name grit

Serves one moxin as a standalone MCP server over stdio. Useful for registering individual moxins with MCP clients directly.

Run as MCP proxy

moxy serve-mcp

Loads the moxyfile hierarchy, spawns child servers, discovers moxins, and serves everything through a single MCP endpoint on stdio. This is the default command when invoked via the MCP protocol.

Configuration

Moxy loads TOML moxyfiles from a directory hierarchy:

  1. ~/.config/moxy/moxyfile (global)
  2. Each parent directory between $HOME and the current directory
  3. ./moxyfile (project-local)

Later files override earlier ones by server name. See moxyfile(5) for the full configuration reference.

Metrics

Moxy emits fire-and-forget statsd metrics over UDP for every tool dispatch, resource read, and prompt get (classic line protocol, no tags):

moxy.<server>.<tool>.duration:<ms>|ms
moxy.<server>.<tool>.success:1|c      # or .failure / .abandoned
moxy.<segment>.resource_read.*        # resources/read; <segment> is the URI
                                      # scheme (moxy, madder) or <server>/ prefix
moxy.<server>.prompt_get.*            # prompts/get

<server> is the child-server/moxin name (builtin for meta tools like restart and batch); names are sanitized to [a-zA-Z0-9_-], so the resource_read/prompt_get families can't collide with the synthetic resource-read tool. A dispatch counts as failure on a dispatch error or a tool-level error result, and abandoned when the client cancelled the call. Standalone-moxin serving (moxy serve-moxin) emits the same dispatch family. Configuration:

  • STATSD_HOST (default 127.0.0.1) and STATSD_PORT (default 8125), dialed once at startup
  • MOXY_DISABLE_STATSD=1 disables emission entirely (a failed dial also runs disabled)

Metrics never block or fail a dispatch — emit errors are swallowed.

Documentation

Moxy ships with man pages:

  • moxy(1) — command overview and subcommands
  • moxyfile(5) — configuration file format and hierarchy
  • moxy-hooks(5) — hook configuration for Claude Code integration
  • moxin(7) — moxin format and authoring guide

View them with man moxy, man moxyfile, man moxy-hooks, or man moxin after installing via nix.

License

MIT

Ver o original no GitHub

Bom para

Relacionados