Teletype MCP

Conecta asistentes de IA a Teletype para leer conversaciones de clientes, gestionar contactos y enviar respuestas a través de canales de mensajería.

GitHub

Prueba este MCPPatrocinado

Servidor MCP alojado

npx add-mcp 'https://mcp.teletype.app/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Español | Русский

Servidor Teletype MCP

Arquitectura | Clientes MCP | Referencia de herramientas

Servidor MCP para Teletype. Sus herramientas cubren el trabajo diario de soporte: encontrar y leer conversaciones, consultar perfiles de clientes, enviar respuestas, añadir contexto interno y comprobar el estado del proyecto.

Inicio rápido

VS Code solicita el token del proyecto al conectarse. Para Cursor, establece TELETYPE_API_TOKEN en el entorno de la aplicación antes de abrir la conexión. Consulta la guía de clientes.

Servidor alojado (recomendado). Teletype ejecuta el servidor MCP en https://mcp.teletype.app/mcp. Conéctate con el token de la API pública de tu proyecto. No se necesita instalación local. En Claude Code:

claude mcp add --transport http teletype https://mcp.teletype.app/mcp \
  --header "X-Teletype-Api-Token: your-teletype-public-api-token"

o fusiona este archivo en .mcp.json (Claude Code expande ${TELETYPE_API_TOKEN} desde el entorno):

{
  "mcpServers": {
    "teletype": {
      "type": "http",
      "url": "https://mcp.teletype.app/mcp",
      "headers": { "X-Teletype-Api-Token": "${TELETYPE_API_TOKEN}" }
    }
  }
}

Para Claude Code y Codex, los plugins instalan el servidor y la habilidad teletype-support en un solo paso. Consulta Plugins para Claude Code, Codex y Cursor.

Ejecutar localmente. Los usuarios de Claude Desktop en macOS o Windows pueden descargar el archivo .mcpb desde los lanzamientos del proyecto, abrirlo e introducir su token de API pública de Teletype cuando se solicite. Para ejecutar desde el código fuente, usa npm ci && npm run build y luego apunta un cliente MCP a node /absolute/path/to/dist/index.js --stdio con TELETYPE_API_TOKEN en su entorno.

Para otros clientes, usa Node.js 20.19+, 22.13+ o 24.x y un token de API pública de Teletype. También puedes añadir este servidor a claude_desktop_config.json de Claude Desktop manualmente:

{
  "mcpServers": {
    "teletype": {
      "command": "npx",
      "args": ["-y", "teletype-mcp-server", "--stdio"],
      "env": { "TELETYPE_API_TOKEN": "your-teletype-public-api-token" }
    }
  }
}

Reinicia el cliente y pídele que liste las herramientas de Teletype. El servidor admite el protocolo de enlace initialize de 2025 y MCP 2026-07-28. Puedes comprobar la configuración local sin contactar con Teletype:

TELETYPE_API_TOKEN=your-token npx -y teletype-mcp-server doctor --stdio

Para Cursor, Zed y otros clientes MCP, usa el mismo comando, argumentos y variable de entorno.

Para Cursor, VS Code con Copilot, Codex, Claude Code, OpenCode, Antigravity CLI y otros clientes compatibles, consulta Clientes MCP. Los ejemplos cubren conexiones HTTP alojadas y stdio locales. Un endpoint opcional compatible con OpenAI es opcional y solo lo usa eval:model.

Para Claude Code y Codex hay plugins que instalan el servidor, la habilidad teletype-support y admiten comandos de barra en un solo paso. Consulta Plugins para Claude Code, Codex y Cursor.

Herramientas

Las 17 herramientas se agrupan en conjuntos de herramientas: conversations, messaging, admin y meta. Puedes registrarlas todas (por defecto), restringir el servidor a conjuntos seleccionados con --toolsets o ejecutarlo en modo solo lectura con --read-only. La referencia de herramientas documenta cada parámetro.

find_conversations: encuentra conversaciones por estado, canal, tipo de canal (channel_type), cliente, etiqueta, operador, categoría, consulta de búsqueda y paginación (page).
list_clients: lista clientes con paginación o encuentra clientes por teléfono sin cambiar datos.
find_messages: lista mensajes del proyecto o inspecciona texto de mensajes antiguos página a página. Continúa mientras has_more sea verdadero.
lookup_client_profile: devuelve un perfil de cliente con campos personalizados, notas y conversaciones recientes.
read_conversation_thread: lee mensajes y enlaces sin cambiar datos por defecto. mark_seen: true marca la conversación como leída y requiere confirm: true. include_sessions: true añade historial de sesión, session_id selecciona detalles de sesión y include_group_clients: true añade participantes de chat grupal.
read_client_history: lee las conversaciones recientes de un cliente en una sola llamada, hasta cinco diálogos con una porción de mensajes cada uno (dialogs_limit, messages_per_dialog). Úsalo para reunir contexto en varios diálogos antes de responder.
send_reply_to_client: responde a una conversación existente, inicia una nueva mediante /channel/send-message (admite auto_close: true) o crea una conversación sin mensajes mediante /dialog/create (create_dialog_only: true).
create_dialog_by_phone: crea o encuentra un diálogo por teléfono sin enviar un mensaje. Un diálogo abierto existente puede asignarse al propietario del proyecto. Requiere confirm: true y admite dry_run.
send_whatsapp_template: envía una plantilla WABA aprobada a una conversación existente de WhatsApp Edna fuera de la ventana de 24 horas. El ID de plantilla proviene de las plantillas WABA importadas del proyecto, no de la lista de respuestas rápidas.
manage_sent_message: edita texto, elimina o reenvía un mensaje de operador.
annotate_client_record: actualiza la identidad del cliente (name, phone, email, additional_payload, force_additional_payload), etiquetas, notas, elimina notas (delete_note_id), campos personalizados o categoría de diálogo.
resolve_conversation: cierra una conversación, la reasigna a un operador (o autoasigna mediante assign_operator: "auto"), mantiene el diálogo abierto (close: false) o marca diálogos abiertos como respondidos (mark_answered: true) o no respondidos (mark_unanswered: true).
list_workspace_metadata: lista canales (con filtros channel_type y only_active), etiquetas, categorías, plantillas, carpetas de plantillas (template_directories), grupos de operadores y operadores.
get_project_status: devuelve facturación, disponibilidad de operadores y estado técnico del proyecto Teletype.
manage_operator_group: añade/elimina miembros del grupo (add_member, remove_member), añade/elimina canales del grupo (add_channel, remove_channel), establece el rol de supervisor (set_supervisor) y configura la visibilidad de conversaciones del canal (set_channel_visibility).
configure_project_webhook: establece la URL del webhook objetivo y los eventos activos habilitados mediante /project/update-public-api.
get_capabilities: devuelve el mapa de herramientas activo del servidor (nombre y dominio del proyecto, modo solo lectura, conjuntos de herramientas activos, herramientas registradas). Siempre disponible.

Para trabajo no respondido, usa find_conversations con status: "unanswered". Para un inventario de canales, usa list_workspace_metadata con resource: "channels". Para la salud del canal y de la API pública, usa get_project_status con aspect: "technical". Estos filtros evitan datos no relacionados y listas limitadas de all. Al cerrar una conversación, omite category a menos que el usuario haya solicitado una. Si lo hizo, obtén su nombre exacto de resource: "categories" primero. Una categoría desconocida detiene la llamada antes de cualquier cambio.

Las herramientas que cambian datos requieren confirm: true. La marca reduce llamadas accidentales. El cliente MCP aún debe manejar la autorización y el consentimiento del usuario. send_reply_to_client y send_whatsapp_template aceptan dry_run: true para previsualizar el objetivo y el mensaje sin enviar. create_dialog_by_phone acepta dry_run: true para previsualizar el objetivo y los posibles efectos secundarios sin crear ni asignar un diálogo. Una ejecución de prueba no requiere confirm.

Cada herramienta publica un outputSchema. El texto corto de content da el resultado principal y enlaces. El resultado completo está en structuredContent, que el servidor verifica contra el esquema. Las escrituras parciales devuelven un error con las acciones aplicadas y los fallos. Verifica el estado remoto antes de reintentar una escritura después de un tiempo de espera, cancelación o error de esquema.

Los decodificadores de respuesta de la API pública aceptan campos adicionales. Verifican los campos de respuesta utilizados para lecturas, escrituras y reporte de estado. Un campo requerido inutilizable produce un error de herramienta sin detener el servidor MCP.

Prompts

El servidor proporciona estos prompts de soporte:

triage-inbox: clasifica diálogos entrantes no respondidos por urgencia y prioridad.
draft-reply: redacta una respuesta al cliente basada en el historial de conversación y el tono.
client-summary: resume el perfil del cliente, problemas pasados y temas abiertos.
escalate-issue: genera un paquete de escalamiento estructurado para ingeniería o soporte senior.
shift-handover: informe de traspaso de turno de soporte que cubre la cola de pendientes, la salud del canal y la disponibilidad del equipo.

Recursos y plantillas

Recursos estáticos

teletype://project/status: estado actual del proyecto, estado del canal y saldo.
teletype://workspace/metadata: canales del espacio de trabajo, operadores, grupos, etiquetas y categorías.
teletype://dialogs/unanswered: cola actual de diálogos de clientes no respondidos con enlaces directos.

Plantillas de recursos

teletype://dialogs/{dialogId}: historial completo de mensajes para un diálogo específico por ID.
teletype://clients/{clientId}: perfil del cliente, etiquetas y notas por ID de cliente.

Plugins para Claude Code, Codex y Cursor

El repositorio contiene marketplaces para Claude Code, Codex y Cursor. El directorio plugin/ incluye .claude-plugin/plugin.json y .cursor-plugin/plugin.json, los manifiestos portátiles de Agent Plugins plugin.json y mcp.json, la habilidad de soporte compartida y comandos. Consulta el README del plugin para configuración y acceso a datos.

Claude Code

El plugin incluye el servidor MCP alojado (https://mcp.teletype.app/mcp, autenticado con el encabezado X-Teletype-Api-Token proporcionado por el campo de configuración sensible del plugin), la habilidad teletype-support con los flujos de trabajo de soporte y reglas de seguridad, y cinco comandos de barra que reflejan los prompts MCP del servidor: /triage-inbox, /draft-reply, /client-summary, /escalate-issue, /shift-handover.

/plugin marketplace add Teletype-App/teletype-mcp-server
/plugin install teletype@teletype-mcp-server

Al habilitar el plugin, introduce el token en el campo Token de API pública de Teletype. Este campo sensible requerido userConfig almacena el valor en el almacén de credenciales seguro de Claude y proporciona el encabezado HTTP. Usa una versión actualizada de Claude Code con soporte para userConfig. La habilidad lleva las regulaciones de múltiples pasos que no caben en las descripciones de herramientas: orden de clasificación, ejecución de prueba antes de un envío ambiguo, búsqueda de categoría antes de cerrar. Se activa en tareas de soporte sin comando de barra. Los cinco flujos de trabajo también existen como prompts MCP para clientes que los muestran. Los comandos cubren las sesiones donde no se muestran.

Cursor

El manifiesto nativo de Cursor se conecta al servidor alojado e incluye la habilidad compartida y los comandos. Para una instalación de marketplace, establece TELETYPE_API_TOKEN en Plugins → Configurar. Para conectarte directamente sin plugin, sigue la guía de configuración de Cursor.

Codex

Exporta TELETYPE_API_TOKEN en el shell antes de iniciar Codex. El servidor stdio incluido lo hereda del proceso de Codex.

codex plugin marketplace add Teletype-App/teletype-mcp-server

Luego ejecuta /plugins en Codex, instala teletype e inicia una nueva sesión. El plugin añade la habilidad y el servidor stdio local (la especificación de Agent Plugins no permite expansión de variables en encabezados HTTP, por lo que un token por usuario no puede incluirse dentro del plugin). Para conectar Codex al endpoint alojado en su lugar, añádelo a ~/.codex/config.toml:

[mcp_servers.teletype]
url = "https://mcp.teletype.app/mcp"
env_http_headers = { "X-Teletype-Api-Token" = "TELETYPE_API_TOKEN" }

Codex también lee habilidades sin plugins desde .agents/skills en el repositorio o ~/.agents/skills para el usuario.

Otros agentes

Instala la habilidad de soporte con la CLI de Skills:

npx skills add Teletype-App/teletype-mcp-server --skill teletype-support

Selecciona tu agente y alcance de instalación cuando se solicite. Este comando instala las instrucciones de flujo de trabajo. Conecta el servidor MCP por separado usando la guía de clientes.

La habilidad usa el formato abierto Agent Skills, compatible con OpenCode, Cursor, Gemini CLI, GitHub Copilot, Goose y otros. El paquete npm incluye la habilidad, así que después de una instalación regular:

mkdir -p ~/.agents/skills
cp -r node_modules/teletype-mcp-server/plugin/skills/teletype-support ~/.agents/skills/

Uso de CLI

El servidor acepta banderas de CLI y variables de entorno:

teletype-mcp-server --help
# Options:
#   -s, --stdio       Use stdio transport
#   --http            Use Streamable HTTP transport (default)
#   -p, --port <num>  Port for HTTP transport (default: 4311)
#   --host <ip>       Host for HTTP transport (default: 127.0.0.1)
#   -v, --version     Show version
#   -h, --help        Show help

--read-only y --toolsets <names> (conversations,messaging,admin,meta separados por comas) filtran qué herramientas registra el servidor antes de que cualquier cliente se conecte. get_capabilities siempre permanece registrado y reporta el mapa activo.

Requisitos e instalación local

Node.js 20.19+, 22.13+ o 24.x para la CLI empaquetada.
un token de API pública de Teletype desde la configuración del proyecto.

Las mismas versiones de Node.js admiten los scripts locales npm start, npm run dev y npm run eval:model.

npm ci
npm run build
cp .env.example .env

Transporte stdio

Use stdio para un cliente MCP personal local. El proceso lee el token de su entorno. Las cargas de archivos a través de attachment_path están deshabilitadas por defecto. Para habilitarlas, establece ENABLE_LOCAL_UPLOADS=true y lista los directorios permitidos en TELETYPE_ALLOWED_FILE_ROOTS. Usa directorios que otros usuarios locales no puedan escribir.

Configuración de compilación local:

{
  "mcpServers": {
    "teletype": {
      "command": "node",
      "args": ["/absolute/path/to/teletype-mcp-server/dist/index.js", "--stdio"],
      "env": { "TELETYPE_API_TOKEN": "..." }
    }
  }
}

Ejecútalo localmente:

TRANSPORT=stdio TELETYPE_API_TOKEN=... npm start

Transporte HTTP Streamable

El servicio alojado en https://mcp.teletype.app usa este endpoint. La configuración a continuación es para autoalojamiento.

El endpoint /mcp y el transporte stdio soportan tanto el handshake initialize de 2025 como MCP 2026-07-28 server/discover. Ambos usan las mismas definiciones de herramientas.

Endpoint: POST /mcp. Envía el token de API de Teletype con cada solicitud en este encabezado:

X-Teletype-Api-Token: <token>

No envíes el token de proyecto de Teletype en Authorization. Usa HTTPS para acceso remoto. Cualquier persona con el token de proyecto puede acceder a sus datos a través del servidor MCP, sujeto a restricciones de implementación.

OAuth está deshabilitado en el endpoint público alojado en https://mcp.teletype.app/mcp. Conéctate con tu token de proyecto en X-Teletype-Api-Token. Para autoalojamiento, el código incluye OAuth opcional, deshabilitado por defecto y habilitado mediante configuración separada.

TRANSPORT=http HOST=127.0.0.1 PORT=4311 npm start

Endpoints HTTP:

Método	Ruta	Propósito
GET	`/`	Página de aterrizaje en ruso e inglés
GET	`/assets/*`	Scripts, estilos, logo y fuentes de la página de aterrizaje
POST	`/mcp`	MCP HTTP Streamable sin estado
GET	`/healthz`	Sonda de salud

Cada solicitud HTTP obtiene su propio par de servidor y transporte MCP, por lo que los inquilinos concurrentes no comparten respuestas ni contexto. El servidor limita las solicitudes concurrentes globalmente y por token. Devuelve 429 con Retry-After cuando se alcanza un límite. El transporte HTTP no puede leer archivos locales.

Docker

La imagen se ejecuta como un usuario sin privilegios y escucha en el puerto 4311 por defecto:

docker build -t teletype-mcp-server .
docker run --rm -p 127.0.0.1:4311:4311 \
  -e PUBLIC_BASE_URL=http://127.0.0.1:4311 \
  teletype-mcp-server

Para un dominio público, establece su origen en PUBLIC_BASE_URL y termina HTTPS en el proxy inverso.

Para un cliente MCP que inicia un contenedor sobre stdio, compila el objetivo stdio y reenvía el token desde tu entorno privado. Mantén stdin abierto con -i y omite -t, que interferiría con los mensajes MCP:

docker build --target stdio -t teletype-mcp-stdio .
docker run --rm -i -e TELETYPE_API_TOKEN teletype-mcp-stdio

El objetivo stdio se ejecuta como el mismo usuario sin privilegios y no expone un puerto HTTP ni usa una verificación de salud HTTP. Establece TELETYPE_MCP_READ_ONLY=true para deshabilitar las herramientas de escritura.

Configuración

Variable	Predeterminado
`TRANSPORT`	`http`
`HOST` / `PORT`	`127.0.0.1` / `4311`
`PUBLIC_BASE_URL`	`http://127.0.0.1:4311`
`ALLOWED_ORIGINS`	orígenes adicionales separados por comas
`OAUTH_ENABLED`	`false`
`OAUTH_DB_PATH`	ruta SQLite persistente cuando OAuth está habilitado
`OAUTH_ENCRYPTION_KEY`	clave hexadecimal privada de 64 caracteres cuando OAuth está habilitado
`TELETYPE_API_TOKEN`	requerido para stdio
`TELETYPE_API_BASE`	`https://api.teletype.app/public/api/v1`
`TELETYPE_PROJECT_URL`	`teletype.app`
`TELETYPE_MCP_LOCALE`	`en` (`ru` para texto en ruso)
`TELETYPE_MCP_READ_ONLY`	`true` anula el registro de herramientas de escritura
`TELETYPE_MCP_TOOLSETS`	conjuntos de herramientas separados por comas para registrar
`REQUEST_TIMEOUT_MS`	`15000`
`MAX_RESPONSE_BYTES`	`5000000`
`MAX_UPLOAD_BYTES`	`20000000`
`MAX_CONCURRENT_REQUESTS`	`32`
`MAX_CONCURRENT_PER_TOKEN`	`4`
`ENABLE_LOCAL_UPLOADS`	`false`
`TELETYPE_ALLOWED_FILE_ROOTS`	directorios permitidos separados por comas

PUBLIC_BASE_URL y cada entrada en ALLOWED_ORIGINS deben ser un origen sin ruta, consulta o fragmento. El servidor valida el valor cada vez que un cliente envía un encabezado Origin.

TELETYPE_MCP_LOCALE establece el idioma de las instrucciones MCP, descripciones de herramientas, indicaciones, sugerencias y errores generados por el servidor. Se aplica a todo el proceso del servidor, incluidos todos los clientes HTTP. Establécelo en ru en el entorno del servidor MCP para texto en ruso. Los nombres de herramientas, nombres de argumentos y campos structuredContent permanecen iguales. Los datos del cliente y los detalles de error de Teletype mantienen su idioma original. El servidor no infiere la configuración regional del sistema operativo host o del token de API.

Solución de problemas

El cliente no puede conectarse: ejecuta doctor --stdio con tu token, luego verifica la configuración de transporte del cliente.
stdio transport requires TELETYPE_API_TOKEN: agrega el token al entorno del servidor del cliente. El doctor verifica solo la configuración local, no la validez del token.
Herramientas faltantes en la lista del cliente: ejecuta doctor --stdio y verifica sus líneas Mode y Toolsets, o llama a get_capabilities. --read-only y --toolsets ocultan herramientas en el momento del registro.
HTTP 401 o 403 de Teletype: verifica el token en la configuración del proyecto de Teletype.
Una escritura expiró o fue cancelada: verifica el estado de la conversación o proyecto antes de enviarla nuevamente.

Desarrollo

npm run dev
npm run dev:stdio
npm run check:fast
npm run check
npm run test:mutation
npm run mcp:smoke
npm run package:smoke
npm run bundle:mcpb
npm run mcp:conformance

mcp:smoke verifica los handshakes de 2025 y 2026-07-28 sobre HTTP y stdio con el cliente SDK. Las pruebas también verifican el aislamiento de tokens HTTP y rechazan resultados de herramientas que rompen su outputSchema.

package:smoke instala el archivo npm en un directorio temporal y verifica su CLI, exportaciones, ambas versiones de protocolo y el fixture de evaluación. mcp:conformance ejecuta cinco escenarios cortos de la suite de conformidad MCP independiente contra un servidor local y una API de Teletype falsa. Ningún comando contacta un proyecto de Teletype.

bundle:mcpb crea artifacts/teletype-mcp-server-v<version>.mcpb, valida su manifiesto y verifica el servidor empaquetado a través de MCP stdio. No contacta a Teletype.

Evaluación de compatibilidad de modelos

Para ejecutar la evaluación a través de un agente de terminal, conéctalo al fixture de evaluación sin conexión. El agente usa herramientas MCP contra datos falsos de Teletype y puede solicitar métricas separadas de resultado, primer intento, respuesta y seguridad a través de eval_grade_case. No se requiere un endpoint de API de modelo.

Los resultados de evaluación cubren 21 tareas completas y nueve casos de selección de herramientas por cliente de terminal, con recuentos de tokens, duración y costo estimado de tokens equivalente a API.

El comando opcional eval:model ejecuta las mismas verificaciones a través de un endpoint de finalización de chat compatible con OpenAI. Inicia una API de Teletype falsa local y un servidor MCP y no necesita un token de proyecto real ni datos de cliente.

Establece un endpoint que proporcione POST /chat/completions compatible con OpenAI:

cp .env.eval.example .env.eval
# Set EVAL_MODEL_BASE_URL, EVAL_MODEL_NAME, and EVAL_MODEL_API_KEY if needed.
npm run eval:model > eval-report.json

Para una verificación breve de descripciones de herramientas, ejecuta npm run eval:selection > selection-report.json. Envía nueve solicitudes sintéticas al modelo configurado y verifica solo la primera herramienta elegida. No se ejecuta ninguna herramienta de Teletype. Una elección incorrecta o faltante sale con el código 2. Esta verificación no mide si el agente completa la tarea.

La evaluación verifica:

selección de herramientas.
argumentos requeridos y validación en tiempo de ejecución.
sin llamadas de escritura en escenarios de solo lectura.
confirmación antes de enviar o cerrar.
hechos clave de resultados en la respuesta final.

Veintiún escenarios se ejecutan por defecto. EVAL_CASES selecciona un subconjunto, y EVAL_THRESHOLD establece la puntuación de aprobación. Los códigos de salida son 0 para aprobar, 2 para una puntuación por debajo del umbral y 1 para un error de configuración o tiempo de ejecución. El informe JSON va a stdout y los diagnósticos a stderr. La evaluación envía texto de escenario y respuestas de API falsas al endpoint del modelo configurado.

El informe también incluye tasas de resultado, primer intento, respuesta y seguridad. Cada escenario comienza desde un proyecto falso nuevo. Una corrección dentro de una ejecución del agente cuenta para el resultado final pero no cambia la métrica de primer intento.

npm run check:fast ejecuta formato, linting, verificaciones de tipos y pruebas. npm run check agrega Knip, umbrales de cobertura, una puerta de puntuación de mutación del 100% para aislamiento y limitación de solicitudes, la compilación y verificaciones de paquetes con Publint y Are the Types Wrong.

npm run test:mutation ejecuta la suite de mutación completa con un piso de puntuación del 33% y escribe informes en reports/mutation/. Toma más tiempo y no es parte de npm run check.

Consulta SECURITY.md para informar vulnerabilidades y CONTRIBUTING.md para pautas de contribución. El proyecto usa la licencia MIT.