mctop

mctop

Un cliente de terminal para servidores MCP. Conéctate a cualquier servidor, explora sus herramientas, recursos y prompts, invócalos y observa el resultado sin salir de la shell. Luego verifica el contrato del servidor en CI para que una herramienta renombrada o un esquema desviado haga fallar la compilación en lugar de romper un agente en producción.

Piensa en curl y k9s, pero para el Model Context Protocol.

Qué hace

• Explora un servidor de forma interactiva: navega por herramientas, recursos y prompts, completa los argumentos de una herramienta en un formulario guiado por esquema y lee el resultado.
• Scriptéalo sin interfaz: mctop ls para listar, mctop call para llamadas de una sola vez.
• Pruébalo en CI: mctop test spec.yaml ejecuta un contrato y sale con código distinto de cero cuando se rompe.

Instalación

curl -fsSL https://mctop.org/install | sh

O con Homebrew, o con el toolchain de Go:

brew install mctop-org/tap/mctop
go install github.com/mctop-org/mctop@latest

Luego mctop upgrade lo mantiene actualizado, sin importar cómo lo hayas instalado.

Uso

mctop <target>                 open the interactive client against a server
mctop ls <target>              list tools, resources, and prompts
mctop call <target> <tool>     call one tool and print the result
mctop login <url>              log in to an OAuth-protected server
mctop test <spec.yaml>         run a contract, exit 0 on pass, 1 on fail
mctop record <target>          browse a server and save the calls as a spec
mctop upgrade                  update to the latest release

Un objetivo es un comando a ejecutar ("uvx mcp-server-time") o una URL http(s)://. Para un servidor más antiguo que necesite el transporte SSE heredado, añade --sse.

mctop call "uvx mcp-server-time" get_current_time timezone=UTC

Los argumentos son pares key=value (los valores que parecen JSON, como números, booleanos, arrays y objetos, están tipados; cualquier otra cosa es una cadena), o un único objeto --json '{...}'.

Modo interactivo

Ejecuta mctop <target> sin subcomando para abrir el cliente a pantalla completa: navega por herramientas, recursos y prompts; pulsa enter en una herramienta para completar sus argumentos en un formulario guiado por esquema y ejecutarla; lee el resultado y vuelve a empezar.

↑↓ move    enter open    / search    tab switch section    T trace    ? keys    q quit

Los resultados se muestran como campos y tablas legibles en lugar de JSON crudo. Cuando el resultado es una lista de registros, ↑/↓ seleccionan una fila y enter la expande a una vista completa sin truncar; esc vuelve a contraer la lista. Pulsa t para ver el JSON crudo, y para copiar, r para volver a ejecutar, e para editar los argumentos y esc (o ←) para volver atrás.

Pulsa T para ver el protocolo crudo: cada frame JSON-RPC que cruzó el cable, cada uno etiquetado con su dirección, método y hora, sobre su JSON. Se lee como el panel de red del Inspector web, sin salir de la terminal, para que puedas ver exactamente qué devolvió un servidor cuando una llamada te sorprende.

Los movimientos de Vim (h/j/k/l, g/G) están activados por defecto; V los alterna y la elección se recuerda. Las teclas de flecha siempre funcionan de cualquier manera. Pulsa ? para ver la lista completa de teclas.

Autenticación

Para servidores protegidos con OAuth, inicia sesión una vez y mctop gestiona el token a partir de entonces:

mctop login  https://api.example.com/mcp   # opens the browser, caches the token
mctop ls     https://api.example.com/mcp   # uses it automatically
mctop logout https://api.example.com/mcp   # forgets it

El token se guarda en caché por host y se actualiza según sea necesario, así que inicias sesión una vez por servidor, no por comando. Para servidores que aceptan un token estático en su lugar, pásalo con -H (repetible):

mctop ls https://api.example.com/mcp -H "Authorization: Bearer $TOKEN"

Pruebas en CI

Una especificación describe qué debe exponer un servidor y cómo deben comportarse sus llamadas. mctop test sale con código distinto de cero cuando el contrato se rompe, por lo que controla una compilación.

server:
  url: "https://api.example.com/mcp"
  # sse: true                          # for a legacy HTTP+SSE server
  headers:
    Authorization: "Bearer ${TOKEN}"   # expanded from the environment
expect:
  tools: [search, fetch]
calls:
  - tool: search
    args: { query: "hello" }
    assert:
      not_error: true
      contains: "results"

mctop test spec.yaml --report json

No tienes que escribir una especificación a mano: mctop record <target> -o spec.yaml abre el cliente interactivo y guarda cada llamada a herramienta que hagas como un paso de la especificación, verificando el estado de error que observó. Los headers pasados con -H se escriben como referencias de entorno $NAME, por lo que el archivo es seguro para commitear. Afina los pasos grabados con aserciones contains donde fortalezcan el contrato.

Ejemplos

El directorio examples/ contiene especificaciones ejecutables y un pequeño servidor de demostración al que puedes apuntar mctop:

go run ./examples/demoserver
mctop ls http://localhost:8080/mcp

Licencia

MIT, consulta LICENSE.