agent MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

OAuth 2.1 + autenticación basada en scopes lista para usar
Hot-reload: edita la configuración, aparecen nuevos upstreams sin reiniciar
Registro de auditoría en cada llamada a herramienta
Filtrado por etiquetas para que diferentes clientes vean conjuntos distintos de herramientas
Se ejecuta a través de npx @1mcp/agent, binario o Docker

Demo en vivo

Cómo se ve en la práctica

agent.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "agent",
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "agent": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "agent"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add agent -- npx -y agent

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: agent

Ejecutar una puerta de enlace MCP multi-inquilino para diferentes equipos

👤 Equipos de plataforma que sirven a múltiples escuadras con diferentes necesidades de herramientas ⏱ ~45 min advanced

Cuándo usarlo: Diseño e Ingeniería necesitan diferentes MCPs, pero no quieres ejecutar dos puertas de enlace.

Requisitos previos

Un host con Node 20+ o Docker — Cualquier VM pequeña
OAuth IdP (o usa la integrada para local) — Dex, Auth0, Okta — cualquier cosa que hable OIDC

Flujo

Define scopes en la configuración del agente

Redacta una configuración de agente donde el scope 'design' expone MCPs de figma y davinci-resolve, y el scope 'eng' expone github, sentry, postgres.✓ Copiado

→ Configuración con asignaciones de upstream con scope
Conecta OAuth

Conecta el agente a nuestro tenant de Auth0, asigna grupos a scopes.✓ Copiado

→ Los usuarios ven solo las herramientas de su scope
Audita el uso

Muéstrame las últimas 24h de llamadas a herramientas por usuario, agrupadas por nombre de herramienta.✓ Copiado

→ Reporte de uso

Resultado: Una puerta de enlace, vistas de herramientas por equipo, pista de auditoría completa.

Errores comunes

El diseño de scopes se vuelve enredado rápidamente — Comienza con 2-3 scopes amplios (eng-read, eng-write, design) en lugar de scopes por herramienta
Los registros de auditoría consumen mucho espacio en disco — Rota los registros semanalmente o envíalos a un agregador de registros

Combinar con: github · sentry

Desarrollar un MCP personalizado con hot-reload

👤 Constructores iterando en su propio servidor MCP ⏱ ~20 min intermediate

Cuándo usarlo: Estás escribiendo un nuevo MCP y no quieres recargar el IDE después de cada cambio.

Flujo

Registra tu MCP de desarrollo bajo el agente

Añade mi MCP de desarrollo local en node ./my-mcp/dist/index.js bajo la configuración del agente, etiquétalo como 'dev'.✓ Copiado

→ La herramienta aparece en el cliente
Edita, guarda, reinténtalo

Cambié la herramienta. Dime si la nueva versión está activa sin que yo reinicie.✓ Copiado

→ Hot-reload confirmado

Resultado: Un ciclo interno rápido para el desarrollo de MCP.

Errores comunes

El hot-reload puede filtrar controladores de herramientas antiguas si los clientes almacenan caché — Para cambios grandes de interfaz, reinicia el cliente de todas formas

Implementar una puerta de entrada con sanitización para un MCP upstream no confiable

👤 Administradores conscientes de la seguridad que ejecutan MCPs comunitarios ⏱ ~15 min intermediate

Cuándo usarlo: Quieres probar un MCP comunitario pero también quieres protecciones adicionales para la entrada.

Flujo

Habilita la sanitización

Configura el agente 1mcp para habilitar la sanitización de entrada en el upstream 'community-x', bloquea cualquier herramienta que devuelva un payload demasiado grande.✓ Copiado

→ Límites aplicados
Verifica

Llama a una herramienta de ese upstream y confirma las entradas del registro de sanitización.✓ Copiado

→ El registro muestra la llamada sanitizada

Resultado: Un radio de impacto más seguro al experimentar con herramientas comunitarias.

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

agent + proxy-2

Compara 1mcp cargado de características vs tbxark/mcp-proxy minimalista

Ejecuta tanto 1mcp/agent como tbxark/mcp-proxy en el mismo host y compara la latencia de llamadas a herramientas a través de cada uno.✓ Copiado

agent + jetski

Apila analítica encima de 1mcp

Ejecuta 1mcp/agent detrás de Jetski para obtener tanto OAuth como analítica a nivel de prompt.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_tools	(ninguno)	Handshake — manejado por clientes	gratuito
call_tool	name, args	Cualquier invocación	1 llamada upstream
mcp_add	name, command, args	Añade un nuevo upstream dinámicamente (solo admin)	gratuito

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ninguno propio; limitado por cuotas upstream
Tokens por llamada: Pequeño sobrecargo de proxy
Monetario: Gratuito, MIT
Consejo: Habilita auditoría solo en upstreams capaces de escribir — los registros de solo lectura llenan el disco rápidamente sin beneficio.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: Configuración de cliente OAuth + credenciales del servidor upstream

Almacenamiento de credenciales: Variables de entorno y archivo de configuración; usa un administrador de secretos para producción

Salida de datos: El agente reenvía solo a upstreams configurados

No conceder nunca: scope de admin a usuarios finales — reserva para el equipo de plataforma

Rota los registros de auditoría — agentes de larga duración acumulan GB de historial de llamadas a herramientas.
Los scopes de OAuth son solo tan seguros como tu mapeo de grupos IdP; audita quién está en qué grupo trimestralmente.

Resolución de problemas

Errores comunes y soluciones

Hot reload no detectó mi cambio de configuración

Verifica que el observador de archivos tenga permiso en el directorio montado (los bind mounts de Docker en macOS pueden perder eventos). Recurre a SIGHUP.

Verificar: docker exec agent kill -HUP 1

Token de OAuth rechazado

La reclamación de scope no se asigna a ningún scope configurado. Verifica los registros del agente para la reclamación y alinea la configuración.

Verificar: Decodifica JWT en jwt.io

El MCP upstream falla en la verificación de salud

Ejecuta el comando upstream manualmente para ver su stderr. Los registros del agente solo informan el código de salida.

Verificar: docker exec agent sh -c '<upstream command>'

Lista de herramientas vacía para un usuario

Los scopes de ese usuario no coinciden con las etiquetas de scope requeridas de ninguna herramienta.

Verificar: Verifica el mapeo de scope en la configuración vs reclamaciones JWT

Alternativas

agent vs otros

Alternativa	Cuándo usarla	Contrapartida
tbxark/mcp-proxy	Quieres un binario Go minimalista sin OAuth	Sin autenticación, sin hot-reload, sin scopes
Jetski	Quieres dashboards de analítica completos y DCR	Se requiere infraestructura K8s + Postgres

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills