Teletype MCP

Conecte assistentes de IA ao Teletype para ler conversas com clientes, gerenciar contatos e enviar respostas em canais de mensagens.

GitHub

Experimente este MCPPatrocinado

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

English | Русский

Servidor Teletype MCP

Arquitetura | Clientes MCP | Referência de ferramentas

Servidor MCP para Teletype. Suas ferramentas cobrem o trabalho diário de suporte: encontrar e ler conversas, consultar perfis de clientes, enviar respostas, adicionar contexto interno e verificar o status do projeto.

Início rápido

O VS Code solicita o token do projeto ao conectar. Para o Cursor, defina TELETYPE_API_TOKEN no ambiente do aplicativo antes de abrir a conexão. Consulte o guia do cliente.

Servidor hospedado (recomendado). A Teletype executa o servidor MCP em https://mcp.teletype.app/mcp. Conecte-se com o token da API Pública do seu projeto. Nenhuma instalação local é necessária. No Claude Code:

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

ou mescle este arquivo em .mcp.json (o Claude Code expande ${TELETYPE_API_TOKEN} a partir do ambiente):

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

Para Claude Code e Codex, os plugins instalam o servidor e a habilidade teletype-support em uma única etapa. Consulte Plugins para Claude Code, Codex e Cursor.

Executar localmente. Usuários do Claude Desktop no macOS ou Windows podem baixar o arquivo .mcpb dos releases do projeto, abri-lo e inserir o token da API Pública da Teletype quando solicitado. Para executar a partir do código-fonte, use npm ci && npm run build e aponte um cliente MCP para node /absolute/path/to/dist/index.js --stdio com TELETYPE_API_TOKEN no ambiente.

Para outros clientes, use Node.js 20.19+, 22.13+ ou 24.x e um token da API Pública da Teletype. Você também pode adicionar este servidor ao claude_desktop_config.json do Claude Desktop manualmente:

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

Reinicie o cliente e peça para listar as ferramentas da Teletype. O servidor suporta o handshake initialize de 2025 e o MCP 2026-07-28. Você pode verificar a configuração local sem contatar a Teletype:

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

Para Cursor, Zed e outros clientes MCP, use o mesmo comando, argumentos e variável de ambiente.

Para Cursor, VS Code com Copilot, Codex, Claude Code, OpenCode, Antigravity CLI e outros clientes suportados, consulte Clientes MCP. Os exemplos cobrem conexões HTTP hospedadas e stdio locais. Um endpoint separado compatível com OpenAI é opcional e usado apenas por eval:model.

Para Claude Code e Codex, existem plugins que instalam o servidor, a habilidade teletype-support e suportam comandos de barra em uma única etapa. Consulte Plugins para Claude Code, Codex e Cursor.

Ferramentas

As 17 ferramentas são agrupadas em conjuntos de ferramentas: conversations, messaging, admin e meta. Você pode registrar todas (padrão), restringir o servidor a conjuntos selecionados com --toolsets ou executá-lo somente leitura com --read-only. A referência de ferramentas documenta cada parâmetro.

find_conversations: encontre conversas por status, canal, tipo de canal (channel_type), cliente, tag, operador, categoria, consulta de pesquisa e paginação (page).
list_clients: liste clientes com paginação ou encontre clientes por telefone sem alterar dados.
find_messages: liste mensagens do projeto ou inspecione textos de mensagens mais antigas página por página. Continue enquanto has_more for verdadeiro.
lookup_client_profile: retorne um perfil de cliente com campos personalizados, notas e conversas recentes.
read_conversation_thread: leia mensagens e links sem alterar dados por padrão. mark_seen: true marca a conversa como lida e requer confirm: true. include_sessions: true adiciona histórico de sessão, session_id seleciona detalhes da sessão e include_group_clients: true adiciona participantes do chat em grupo.
read_client_history: leia as conversas recentes de um cliente em uma única chamada, até cinco diálogos com uma fatia de mensagens cada (dialogs_limit, messages_per_dialog). Use para reunir contexto em vários diálogos antes de responder.
send_reply_to_client: responda a uma conversa existente, inicie uma nova via /channel/send-message (suporta auto_close: true) ou crie uma conversa sem mensagens via /dialog/create (create_dialog_only: true).
create_dialog_by_phone: crie ou encontre um diálogo por telefone sem enviar mensagem. Um diálogo aberto existente pode ser atribuído ao proprietário do projeto. Requer confirm: true e suporta dry_run.
send_whatsapp_template: envie um modelo WABA aprovado para uma conversa existente do WhatsApp Edna fora da janela de 24h. O ID do modelo vem dos modelos WABA importados do projeto, não da lista de respostas rápidas.
manage_sent_message: edite texto, exclua ou reenvie uma mensagem de operador.
annotate_client_record: atualize a identidade do cliente (name, phone, email, additional_payload, force_additional_payload), tags, notas, exclua notas (delete_note_id), campos personalizados ou categoria do diálogo.
resolve_conversation: feche uma conversa, reatribua-a a um operador (ou atribua automaticamente via assign_operator: "auto"), mantenha o diálogo aberto (close: false) ou marque diálogos abertos como respondidos (mark_answered: true) ou não respondidos (mark_unanswered: true).
list_workspace_metadata: liste canais (com filtros channel_type e only_active), tags, categorias, modelos, pastas de modelos (template_directories), grupos de operadores e operadores.
get_project_status: retorne cobrança, disponibilidade de operadores e status técnico do projeto Teletype.
manage_operator_group: adicione/remova membros do grupo (add_member, remove_member), adicione/remova canais do grupo (add_channel, remove_channel), defina o papel de supervisor (set_supervisor) e configure a visibilidade de conversas do canal (set_channel_visibility).
configure_project_webhook: defina a URL do webhook de destino e os eventos ativos habilitados via /project/update-public-api.
get_capabilities: retorne o mapa de ferramentas ativo do servidor (nome do projeto e domínio, modo somente leitura, conjuntos de ferramentas ativos, ferramentas registradas). Sempre disponível.

Para trabalho não respondido, use find_conversations com status: "unanswered". Para um inventário de canais, use list_workspace_metadata com resource: "channels". Para a saúde do canal e da API Pública, use get_project_status com aspect: "technical". Esses filtros evitam dados não relacionados e listas limitadas de all. Ao fechar uma conversa, omita category a menos que o usuário tenha solicitado uma. Se solicitado, busque o nome exato de resource: "categories" primeiro. Uma categoria desconhecida interrompe a chamada antes de qualquer alteração.

Ferramentas que alteram dados exigem confirm: true. A flag reduz chamadas acidentais. O cliente MCP ainda deve lidar com autorização e consentimento do usuário. send_reply_to_client e send_whatsapp_template aceitam dry_run: true para pré-visualizar o destino e a mensagem sem enviar. create_dialog_by_phone aceita dry_run: true para pré-visualizar o destino e possíveis efeitos colaterais sem criar ou atribuir um diálogo. Uma execução de teste não requer confirm.

Cada ferramenta publica um outputSchema. O texto curto de content dá o resultado principal e links. O resultado completo está em structuredContent, que o servidor verifica contra o esquema. Gravações parciais retornam um erro com as ações aplicadas e falhas. Verifique o estado remoto antes de tentar novamente uma gravação após timeout, cancelamento ou erro de esquema.

Os decodificadores de resposta da API Pública aceitam campos adicionais. Eles verificam os campos de resposta usados para leituras, gravações e relatórios de status. Um campo obrigatório inutilizável produz um erro de ferramenta sem interromper o servidor MCP.

Prompts

O servidor fornece estes prompts de suporte:

triage-inbox: triagem de diálogos recebidos não respondidos por urgência e prioridade.
draft-reply: rascunho de resposta ao cliente com base no histórico da conversa e no tom.
client-summary: resumo do perfil do cliente, problemas passados e tópicos abertos.
escalate-issue: geração de um pacote de escalonamento estruturado para engenharia ou suporte sênior.
shift-handover: relatório de handover de turno de suporte cobrindo a fila de pendências, a saúde do canal e a disponibilidade da equipe.

Recursos e Modelos

Recursos Estáticos

teletype://project/status: status atual do projeto, status do canal e saldo.
teletype://workspace/metadata: canais do workspace, operadores, grupos, tags e categorias.
teletype://dialogs/unanswered: fila atual de diálogos de clientes não respondidos com links diretos.

Modelos de Recursos

teletype://dialogs/{dialogId}: histórico completo de mensagens para um diálogo específico por ID.
teletype://clients/{clientId}: perfil do cliente, tags e notas por ID do cliente.

Plugins para Claude Code, Codex e Cursor

O repositório contém marketplaces para Claude Code, Codex e Cursor. O diretório plugin/ inclui .claude-plugin/plugin.json e .cursor-plugin/plugin.json, os manifestos portáteis Agent Plugins plugin.json e mcp.json, a habilidade de suporte compartilhada e comandos. Consulte o README do plugin para configuração e acesso a dados.

Claude Code

O plugin agrupa o servidor MCP hospedado (https://mcp.teletype.app/mcp, autenticado com o cabeçalho X-Teletype-Api-Token fornecido pelo campo de configuração sensível do plugin), a habilidade teletype-support com os fluxos de trabalho de suporte e regras de segurança, e cinco comandos de barra que espelham os prompts MCP do 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

Ao habilitar o plugin, insira o token no campo Teletype Public API token. Este campo sensível obrigatório userConfig armazena o valor no armazenamento seguro de credenciais do Claude e fornece o cabeçalho HTTP. Use uma versão atualizada do Claude Code com suporte a userConfig. A habilidade carrega as regulamentações de várias etapas que não cabem nas descrições das ferramentas: ordem de triagem, execução de teste antes de um envio ambíguo, consulta de categoria antes de fechar. Ela é acionada em tarefas de suporte sem comando de barra. Os cinco fluxos de trabalho também existem como prompts MCP para clientes que os exibem. Os comandos cobrem as sessões onde eles não são exibidos.

Cursor

O manifesto nativo do Cursor conecta-se ao servidor hospedado e inclui a habilidade compartilhada e comandos. Para instalação via marketplace, defina TELETYPE_API_TOKEN em Plugins → Configure. Para conectar diretamente sem plugin, siga o guia de configuração do Cursor.

Codex

Exporte TELETYPE_API_TOKEN no shell antes de iniciar o Codex. O servidor stdio incluído o herda do processo do Codex.

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

Em seguida, execute /plugins no Codex, instale teletype e inicie uma nova sessão. O plugin adiciona a habilidade e o servidor stdio local (a especificação Agent Plugins não permite expansão de variáveis em cabeçalhos HTTP, então um token por usuário não pode ser incluído no plugin). Para conectar o Codex ao endpoint hospedado, adicione-o a ~/.codex/config.toml:

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

O Codex também lê habilidades sem plugins de .agents/skills no repositório ou ~/.agents/skills para o usuário.

Outros agentes

Instale a habilidade de suporte com o Skills CLI:

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

Selecione seu agente e escopo de instalação quando solicitado. Este comando instala as instruções do fluxo de trabalho. Conecte o servidor MCP separadamente usando o guia do cliente.

A habilidade usa o formato aberto Agent Skills, suportado por OpenCode, Cursor, Gemini CLI, GitHub Copilot, Goose e outros. O pacote npm inclui a habilidade, então após uma instalação regular:

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

Uso da CLI

O servidor aceita flags de CLI e variáveis de ambiente:

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 e --toolsets <names> (conversations,messaging,admin,meta separados por vírgula) filtram quais ferramentas o servidor registra antes de qualquer cliente conectar. get_capabilities permanece sempre registrado e relata o mapa ativo.

Requisitos e instalação local

Node.js 20.19+, 22.13+ ou 24.x para a CLI empacotada.
um token da API Pública da Teletype das configurações do projeto.

As mesmas versões do Node.js suportam os scripts locais npm start, npm run dev e npm run eval:model.

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

Transporte stdio

Use stdio para um cliente MCP pessoal local. O processo lê o token do seu ambiente. Uploads de arquivos via attachment_path estão desabilitados por padrão. Para habilitá-los, defina ENABLE_LOCAL_UPLOADS=true e liste os diretórios permitidos em TELETYPE_ALLOWED_FILE_ROOTS. Use diretórios que outros usuários locais não possam gravar.

Configuração de build local:

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

Execute localmente:

TRANSPORT=stdio TELETYPE_API_TOKEN=... npm start

Transporte HTTP Streamable

O serviço hospedado em https://mcp.teletype.app usa este endpoint. A configuração abaixo é para auto-hospedagem.

O endpoint /mcp e o transporte stdio suportam tanto o handshake initialize de 2025 quanto o MCP 2026-07-28 server/discover. Ambos usam as mesmas definições de ferramentas.

Endpoint: POST /mcp. Envie o token da API do Teletype com cada requisição neste cabeçalho:

X-Teletype-Api-Token: <token>

Não envie o token do projeto Teletype em Authorization. Use HTTPS para acesso remoto. Qualquer pessoa com o token do projeto pode acessar seus dados através do servidor MCP, sujeito a restrições de implantação.

OAuth está desabilitado no endpoint público hospedado em https://mcp.teletype.app/mcp. Conecte-se com seu token de projeto em X-Teletype-Api-Token. Para auto-hospedagem, o código inclui OAuth opcional, desabilitado por padrão e habilitado através de configuração separada.

TRANSPORT=http HOST=127.0.0.1 PORT=4311 npm start

Endpoints HTTP:

Método	Caminho	Propósito
GET	`/`	Página de destino em russo e inglês
GET	`/assets/*`	Scripts, estilos, logotipo e fontes da página de destino
POST	`/mcp`	MCP HTTP Streamable sem estado
GET	`/healthz`	Sonda de saúde

Cada requisição HTTP recebe seu próprio par de Servidor e transporte MCP, então locatários concorrentes não compartilham respostas ou contexto. O servidor limita requisições concorrentes globalmente e por token. Ele retorna 429 com Retry-After quando um limite é atingido. O transporte HTTP não pode ler arquivos locais.

Docker

A imagem roda como um usuário sem privilégios e escuta na porta 4311 por padrão:

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 um domínio público, defina sua origem em PUBLIC_BASE_URL e encerre HTTPS no proxy reverso.

Para um cliente MCP que inicia um contêiner via stdio, construa o alvo stdio e encaminhe o token do seu ambiente privado. Mantenha o stdin aberto com -i e omita -t, que interferiria nas mensagens MCP:

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

O alvo stdio roda como o mesmo usuário sem privilégios e não expõe uma porta HTTP nem usa uma verificação de saúde HTTP. Defina TELETYPE_MCP_READ_ONLY=true para desabilitar ferramentas de escrita.

Configuração

Variável	Padrão
`TRANSPORT`	`http`
`HOST` / `PORT`	`127.0.0.1` / `4311`
`PUBLIC_BASE_URL`	`http://127.0.0.1:4311`
`ALLOWED_ORIGINS`	origens adicionais separadas por vírgula
`OAUTH_ENABLED`	`false`
`OAUTH_DB_PATH`	caminho SQLite persistente quando OAuth está habilitado
`OAUTH_ENCRYPTION_KEY`	chave hex privada de 64 caracteres quando OAuth está habilitado
`TELETYPE_API_TOKEN`	obrigatório para stdio
`TELETYPE_API_BASE`	`https://api.teletype.app/public/api/v1`
`TELETYPE_PROJECT_URL`	`teletype.app`
`TELETYPE_MCP_LOCALE`	`en` (`ru` para texto em russo)
`TELETYPE_MCP_READ_ONLY`	`true` desregistra ferramentas de escrita
`TELETYPE_MCP_TOOLSETS`	conjuntos de ferramentas separados por vírgula 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`	diretórios permitidos separados por vírgula

PUBLIC_BASE_URL e cada entrada em ALLOWED_ORIGINS devem ser uma origem sem caminho, consulta ou fragmento. O servidor valida o valor sempre que um cliente envia um cabeçalho Origin.

TELETYPE_MCP_LOCALE define o idioma das instruções MCP, descrições de ferramentas, prompts, dicas e erros gerados pelo servidor. Aplica-se a todo o processo do servidor, incluindo todos os clientes HTTP. Defina-o como ru no ambiente do servidor MCP para texto em russo. Nomes de ferramentas, nomes de argumentos e campos structuredContent permanecem os mesmos. Dados do cliente e detalhes de erro do Teletype mantêm seu idioma original. O servidor não infere o locale do sistema operacional host ou do token da API.

Solução de problemas

Cliente não consegue conectar: execute doctor --stdio com seu token e verifique as configurações de transporte do cliente.
stdio transport requires TELETYPE_API_TOKEN: adicione o token ao ambiente do servidor do cliente. O doctor verifica apenas a configuração local, não a validade do token.
Ferramentas ausentes na lista do cliente: execute doctor --stdio e verifique suas linhas Mode e Toolsets, ou chame get_capabilities. --read-only e --toolsets ocultam ferramentas no momento do registro.
HTTP 401 ou 403 do Teletype: verifique o token nas configurações do projeto Teletype.
Uma escrita expirou ou foi cancelada: verifique o estado da conversa ou do projeto antes de enviá-la novamente.

Desenvolvimento

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 os handshakes de 2025 e 2026-07-28 via HTTP e stdio com o cliente SDK. Os testes também verificam o isolamento de token HTTP e rejeitam resultados de ferramentas que quebram seu outputSchema.

package:smoke instala o arquivo npm em um diretório temporário e verifica sua CLI, exportações, ambas as versões de protocolo e o fixture de avaliação. mcp:conformance executa cinco cenários curtos da suíte de conformidade MCP independente contra um servidor local e uma API Teletype falsa. Nenhum comando contata um projeto Teletype.

bundle:mcpb cria artifacts/teletype-mcp-server-v<version>.mcpb, valida seu manifesto e verifica o servidor empacotado via MCP stdio. Não contata o Teletype.

Avaliação de compatibilidade de modelo

Para executar a avaliação através de um agente de terminal, conecte-o ao fixture de avaliação offline. O agente usa ferramentas MCP contra dados falsos do Teletype e pode solicitar métricas separadas de resultado, primeira tentativa, resposta e segurança através de eval_grade_case. Nenhum endpoint de API de modelo é necessário.

Os resultados da avaliação cobrem 21 tarefas completas e nove casos de seleção de ferramentas por cliente de terminal, com contagens de tokens, duração e custo estimado de token equivalente à API.

O comando opcional eval:model executa as mesmas verificações através de um endpoint de conclusões de chat compatível com OpenAI. Ele inicia uma API Teletype falsa local e um servidor MCP e não precisa de token de projeto real ou dados de cliente.

Defina um endpoint que forneça POST /chat/completions compatível com 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 uma verificação curta das descrições de ferramentas, execute npm run eval:selection > selection-report.json. Ele envia nove solicitações sintéticas ao modelo configurado e verifica apenas a primeira ferramenta escolhida. Nenhuma ferramenta Teletype é executada. Uma escolha errada ou ausente sai com código 2. Esta verificação não mede se o agente conclui a tarefa.

A avaliação verifica:

seleção de ferramentas.
argumentos obrigatórios e validação em tempo de execução.
nenhuma chamada de escrita em cenários somente leitura.
confirmação antes de enviar ou fechar.
fatos-chave do resultado na resposta final.

Vinte e um cenários são executados por padrão. EVAL_CASES seleciona um subconjunto, e EVAL_THRESHOLD define a pontuação de aprovação. Os códigos de saída são 0 para aprovação, 2 para uma pontuação abaixo do limite e 1 para um erro de configuração ou tempo de execução. O relatório JSON vai para stdout e os diagnósticos vão para stderr. A avaliação envia texto de cenário e respostas falsas da API ao endpoint do modelo configurado.

O relatório também inclui taxas de resultado, primeira tentativa, resposta e segurança. Cada cenário começa de um projeto falso novo. Uma correção dentro de uma execução do agente conta para o resultado final, mas não altera a métrica de primeira tentativa.

npm run check:fast executa formatação, linting, verificações de tipo e testes. npm run check adiciona Knip, limites de cobertura, um limite de pontuação de mutação de 100% para isolamento e limitação de solicitações, o build e verificações de pacote com Publint e Are the Types Wrong.

npm run test:mutation executa a suíte de mutação completa com um piso de pontuação de 33% e escreve relatórios em reports/mutation/. Leva mais tempo e não faz parte de npm run check.

Veja SECURITY.md para relatar vulnerabilidades e CONTRIBUTING.md para diretrizes de contribuição. O projeto usa a licença MIT.