@proxycept/mcp — puente stdio hacia un servidor MCP de Proxycept

Un puente ligero stdio↔HTTP. Ejecuta un servidor Model Context Protocol en stdio y reenvía cada mensaje JSON-RPC, sin cambios, a un endpoint MCP de Proxycept (https://proxycept.com/api/mcp por defecto) con tu token de API como encabezado bearer.

La mayoría de las personas no necesitan este paquete. El servidor MCP de Proxycept es un servidor HTTP alojado — Claude Desktop y Cursor pueden conectarse a él con una URL y un encabezado Authorization, sin instalación. Este paquete existe para clientes MCP que solo hablan stdio, y porque npx es el modismo de instalación que esperan los listados de directorios.

Para la ruta sin instalación, el catálogo de herramientas y el modelo de seguridad, consulta proxycept.com/docs → "Connect Claude or Cursor", o docs/user-manual.md §14. Configuración → Tokens de API tiene la misma configuración lista para copiar, dirigida a esa implementación y nombrando el token que elegiste — el valor del token se muestra una vez, al crearlo, por lo que el bloque lleva un marcador de posición que debes sustituir.

Lo que no es

No contiene ninguna lista de herramientas, ningún esquema de herramientas y ninguna lógica específica de Proxycept. tools/list lo responde el servidor, no este paquete. Esto es deliberado: el servidor es la única fuente de verdad para el catálogo de herramientas, por lo que una herramienta añadida o modificada en el lado del servidor no necesita un lanzamiento aquí y no hay desviación de versiones que soportar. Si estás leyendo esto porque quieres añadir un caso especial para un nombre de herramienta, ese es el diseño yendo mal.

Requisitos

• Node.js 20 o más reciente (node --version).

• Un token de API de Proxycept (prx_live_…) — Configuración → Tokens de API en proxycept.com/settings.

Usa un token de solo lectura

Crea el token como de solo lectura. Este es el valor predeterminado y es el límite de seguridad, no una sugerencia.

Las herramientas de lectura de Proxycept devuelven tráfico HTTP capturado — contenido que tu cuenta no creó. Un cuerpo de respuesta malicioso de algún upstream puede ser leído por un modelo como si fuera una instrucción ("inyección de prompt"). Dicho claramente:

Un token MCP read_write significa que cualquier cosa que tu proxy capture puede escribir en tu configuración de Proxycept.

Un cuerpo de respuesta del servidor de otra persona, escrito para parecer una instrucción, se convierte en una ruta simulada, un patrón de intercepción o un perfil detenido en tu cuenta. Un token de solo lectura hace que esa cadena sea incompletable dentro de Proxycept: no hay nada a lo que una instrucción inyectada pueda llamar.

Trata cualquier cosa que devuelva una herramienta de Proxycept como datos no confiables, no instrucciones — especialmente si tienes otros servidores MCP conectados que puedan obtener URLs, ejecutar shells o escribir archivos.

Si realmente quieres lectura-escritura

Solo para un cliente al que estés dejando cambiar deliberadamente tu configuración. Entonces, todo esto:

1. Crea un token separado (no actualices el que usas para leer tráfico).

2. Nunca habilites "permitir siempre" para las llamadas a herramientas de Proxycept en tu cliente.

3. No lo uses en la misma sesión en la que estás leyendo tráfico capturado — esa es la combinación exacta que hace que una instrucción inyectada sea procesable.

Una cosa que un token de lectura-escritura aún no puede hacer: reproducir una solicitud capturada. replay_flow reenvía una solicitud real a un tercero con las credenciales capturadas, por lo que requiere que un humano lo apruebe en la consola web de Proxycept (Configuración → Conecta tu cliente de IA). Tu cliente de IA no puede aprobar su propia reproducción, independientemente del token que tenga.

Configúralo — pon el token en el entorno, no en el archivo de configuración

La configuración de tu cliente MCP es JSON en texto plano en el disco, a menudo dentro de un directorio sincronizado con el almacenamiento en la nube. Un token prx_live_… pegado allí es una credencial de larga duración en una copia de seguridad en la que no pensaste. Prefiere el entorno.

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) y la mayoría de los otros clientes usan la misma forma:

{
  "mcpServers": {
    "proxycept": {
      "command": "npx",
      "args": ["-y", "@proxycept/mcp"],
      "env": {
        // Read from your shell environment; the secret itself stays out of this file.
        "PROXYCEPT_API_TOKEN": "${PROXYCEPT_API_TOKEN}"
      }
    }
  }
}

No todos los clientes expanden ${VAR} en su configuración. Si el tuyo no lo hace, la siguiente mejor opción es exportar la variable donde el cliente la heredará (un perfil de shell de inicio de sesión, launchctl setenv en macOS, la unidad systemd en Linux) y eliminar el bloque env por completo — el puente lee PROXYCEPT_API_TOKEN de su entorno heredado. Pegar el token literal en el archivo de configuración funciona, y es la opción a la que recurrir al final.

--token en la línea de comandos es compatible pero desaconsejado: un argumento es visible para cada proceso en la máquina a través de la lista de procesos.

Variables de entorno

Cada variable tiene una bandera correspondiente (--base-url, --url, --token, --timeout, --verbose).

Autoalojado

PROXYCEPT_BASE_URL=https://proxy.internal.example PROXYCEPT_API_TOKEN=… npx -y @proxycept/mcp

Se rechaza http:// en texto plano para cualquier cosa que no sea loopback, por lo que el token nunca puede cruzar un salto en texto claro. Este paquete no proporciona ninguna bandera para deshabilitar la verificación TLS y no lo hará.

Node mismo tiene una — NODE_TLS_REJECT_UNAUTHORIZED=0 desactiva la verificación del certificado para todo el proceso — y el puente se niega a iniciar si encuentra eso configurado para un endpoint que no sea loopback, en lugar de heredarlo silenciosamente. Si te encuentras con ese error, desactiva la variable (revisa tu perfil de shell y el bloque env de tu cliente MCP); casi siempre es un resto de la depuración de algo más, y con ella configurada, tu token saldría a través de una conexión que cualquiera en la ruta puede leer.

Verifica tu configuración

PROXYCEPT_API_TOKEN=prx_live_… npx -y @proxycept/mcp --check

Realiza un handshake MCP real y un tools/list real, luego imprime lo que el servidor dijo:

endpoint: https://proxycept.com/api/mcp
server:   proxycept 1.0.0 (MCP 2025-06-18)
tools:    20 — list_workspaces, list_profiles, …
ok

El recuento de herramientas proviene del servidor, no de este paquete, por lo que cambia sin un lanzamiento aquí. Las herramientas de escritura se enumeran para cada cliente y se rechazan en la capa de API a menos que el token sea read_write — ver más abajo.

Códigos de salida: 0 ok · 1 no se pudo alcanzar o autenticar en el servidor · 2 configuración incorrecta.

Cuando algo está mal

Propiedades de seguridad

• El token se envía como Authorization: Bearer … al origen configurado y a ningún otro lugar. Se rechaza una redirección a un origen diferente, no se sigue — la credencial nunca se entrega a un host que no configuraste. Se sigue la redirección 307/308 del mismo origen (hasta 3 saltos), ya que preservar tanto el origen como el método significa que reenviar la credencial no cambia quién la recibe, y los proxies inversos las emiten; se rechaza 301/302/303, porque reproducir un POST como un GET eliminaría silenciosamente tu solicitud. (El servidor alojado nunca redirige.)

• El token nunca se registra y nunca se devuelve a tu cliente. Cada línea escrita en stderr, y cada mensaje de error que este puente sintetiza para stdout, pasa por un reductor que elimina el secreto configurado, cualquier cosa con forma de token prx_… y cualquier cadena Bearer … — incluso en modo --verbose e incluso una credencial que un servidor devuelva en un cuerpo 4xx/5xx. Ese último caso importa porque stdout es tu cliente MCP: termina en el contexto del modelo y en los registros del cliente. Los seguimientos de pila nunca se imprimen. Hay una prueba para cada uno de esos casos.

• El flujo del protocolo nunca se reescribe. La redacción se aplica a los mensajes que este puente construye, no a las cargas útiles JSON-RPC del servidor — alterarlas corrompería el tráfico que estás depurando. La redacción del tráfico capturado es trabajo del servidor (aplica sus listas de denegación de enmascaramiento en la ruta de lectura).

• No se escribe nada en el disco. Sin caché, sin archivo de configuración, sin almacén de credenciales.

• stdout lleva solo mensajes de protocolo; todos los diagnósticos van a stderr.

• Cero dependencias en tiempo de ejecución. npm ls --omit=dev en este paquete está vacío — la única cadena de suministro es el propio Node.

Desarrollo

cd clients/mcp
npm ci
npm test          # builds, then runs the suite against a fake JSON-RPC server
npm run typecheck

npm run check-package   # asserts the tarball ships every module, the bin, README and LICENSE

Diseño: src/config.ts (resolver + validar configuración), src/redact.ts (redacción + el único registrador), src/http.ts (un POST por mensaje; SSE, política de redirección, mapeo de errores HTTP→JSON-RPC), src/bridge.ts (el bucle de reenvío genérico), src/stdio.ts (encuadre JSON delimitado por nueva línea), src/cli.ts (argumentos, --check, cableado).

Verificado contra un servidor falso

El conjunto de pruebas se ejecuta contra un servidor HTTP JSON-RPC falso en test/helpers.js: reenvío textual (incluyendo métodos de los que este paquete nunca ha oído hablar), forma del encabezado, eco de Mcp-Session-Id y versión del protocolo, streaming SSE, notificaciones 202, mapeo de errores HTTP→MCP, manejo de lotes, la política de redirección, caducidad de sesión, encuadre NDJSON a través de límites de fragmentos, y la ausencia del token de toda salida.

Verificado contra un Proxycept real

--check se ha ejecutado de extremo a extremo contra una API de Control real con el servidor MCP habilitado (V4-T66): negociación de capacidades initialize real, un tools/list real (20 herramientas), con un token prx_live_ de solo lectura. Las incógnitas restantes son específicas de producción — si la implementación alojada emite un Mcp-Session-Id, si una llamada de herramienta larga regresa como JSON o SSE, y la redacción exacta de sus cuerpos 401/403/429. El puente es genérico, por lo que cualquiera de esos puede diferir sin un cambio de código aquí; la prueba en vivo contra https://proxycept.com es el paso 5 de PUBLISHING.md.

Publicación (mantenedores)

Los lanzamientos son manuales a propósito — deliberadamente no hay un trabajo de CI que publique, por lo que un token de flujo de trabajo comrometido no puede enviar un paquete que maneje credenciales de clientes. El runbook completo (creación de org, verificación previa, la secuencia exacta de npm publish --access public, verificación y la ruta de deprecación) está en PUBLISHING.md en este directorio. No forma parte del tarball publicado.