Teletype

English | Русский

Teletype MCP Server

Architecture | MCP clients | Tools reference

MCP server for Teletype. Its tools cover daily support work: finding and reading conversations, looking up customer profiles, sending replies, adding internal context, and checking project status.

Quick start

VS Code asks for the project token when connecting. For Cursor, set TELETYPE_API_TOKEN in the app environment before opening the connection. See the client guide.

Hosted server (recommended). Teletype runs the MCP server at https://mcp.teletype.app/mcp. Connect with your project's Public API token. No local installation is needed. In Claude Code:

claude mcp add --transport http teletype https://mcp.teletype.app/mcp \

--header "X-Teletype-Api-Token: your-teletype-public-api-token"

or merge this file into .mcp.json (Claude Code expands ${TELETYPE_API_TOKEN} from the environment):

{

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

For Claude Code and Codex, plugins install the server and the teletype-support skill in one step. See Plugins for Claude Code, Codex, and Cursor.

Run locally. Claude Desktop users on macOS or Windows can download the .mcpb file from the project's releases, open it, and enter their Teletype Public API token when prompted. To run from source, use npm ci && npm run build, then point an MCP client at node /absolute/path/to/dist/index.js --stdio with TELETYPE_API_TOKEN in its environment.

For other clients, use Node.js 20.19+, 22.13+, or 24.x and a Teletype Public API token. You can also add this server to Claude Desktop's claude_desktop_config.json manually:

{

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

Restart the client and ask it to list Teletype tools. The server supports the 2025 initialize handshake and MCP 2026-07-28. You can check local setup without contacting Teletype:

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

For Cursor, Zed, and other MCP clients, use the same command, arguments, and environment variable.

For Cursor, VS Code with Copilot, Codex, Claude Code, OpenCode, Antigravity CLI, and other supported clients, see MCP clients. The examples cover hosted HTTP and local stdio connections. A separate OpenAI-compatible endpoint is optional and only used by eval:model.

For Claude Code and Codex there are plugins that install the server, the teletype-support skill, and support slash commands in one step. See Plugins for Claude Code, Codex, and Cursor.

Tools

The 17 tools are grouped into toolsets: conversations, messaging, admin, and meta. You can register all of them (default), restrict the server to selected toolsets with --toolsets, or run it read-only with --read-only. The tools reference documents every parameter.

• find_conversations: find conversations by status, channel, channel type (channel_type), customer, tag, operator, category, search query, and pagination (page).
• list_clients: list clients with pagination or find clients by phone without changing data.
• find_messages: list project messages or inspect older message text page by page. Continue while has_more is true.
• lookup_client_profile: return a customer profile with custom fields, notes, and recent conversations.
• read_conversation_thread: read messages and links without changing data by default. mark_seen: true marks the conversation as read and requires confirm: true. include_sessions: true adds session history, session_id selects session details, and include_group_clients: true adds group chat participants.
• read_client_history: read a customer's recent conversations in one call, up to five dialogs with a slice of messages each (dialogs_limit, messages_per_dialog). Use it to gather context across several dialogs before replying.
• send_reply_to_client: reply to an existing conversation, start a new one via /channel/send-message (supports auto_close: true), or create a conversation without messages via /dialog/create (create_dialog_only: true).
• create_dialog_by_phone: create or find a dialog by phone without sending a message. An existing open dialog may be assigned to the project owner. Requires confirm: true and supports dry_run.
• send_whatsapp_template: send an approved WABA template to an existing WhatsApp Edna conversation outside the 24h window. The template ID comes from the project's imported WABA templates, not the quick-reply list.
• manage_sent_message: edit text, delete, or resend an operator message.
• annotate_client_record: update customer identity (name, phone, email, additional_payload, force_additional_payload), tags, notes, delete notes (delete_note_id), custom fields, or dialog category.
• resolve_conversation: close a conversation, reassign it to an operator (or auto-assign via assign_operator: "auto"), keep dialog open (close: false), or mark open dialogs as answered (mark_answered: true) or unanswered (mark_unanswered: true).
• list_workspace_metadata: list channels (with channel_type and only_active filters), tags, categories, templates, template folders (template_directories), operator groups, and operators.
• get_project_status: return billing, operator availability, and technical status of the Teletype project.
• manage_operator_group: add/remove group members (add_member, remove_member), add/remove group channels (add_channel, remove_channel), set the supervisor role (set_supervisor), and configure channel conversation visibility (set_channel_visibility).
• configure_project_webhook: set the target webhook URL and the enabled active events through /project/update-public-api.
• get_capabilities: return the server's active tool map (project name and domain, read-only mode, active toolsets, registered tools). Always available.

For unanswered work, use find_conversations with status: "unanswered". For a channel inventory, use list_workspace_metadata with resource: "channels". For channel and Public API health, use get_project_status with aspect: "technical". These filters avoid unrelated data and limited all lists. When closing a conversation, omit category unless the user requested one. If they did, fetch its exact name from resource: "categories" first. An unknown category stops the call before any changes.

Tools that change data require confirm: true. The flag reduces accidental calls. The MCP client must still handle authorization and user consent. send_reply_to_client and send_whatsapp_template accept dry_run: true to preview the target and message without sending. create_dialog_by_phone accepts dry_run: true to preview the target and possible side effects without creating or assigning a dialog. A dry run does not require confirm.

Each tool publishes an outputSchema. The short content text gives the main result and links. The full result is in structuredContent, which the server checks against the schema. Partial writes return an error with the applied actions and failures. Check the remote state before retrying a write after a timeout, cancellation, or schema error.

The Public API response decoders accept additional fields. They check the response fields used for reads, writes, and status reporting. An unusable required field produces a tool error without stopping the MCP server.

Prompts

The server provides these support prompts:

• triage-inbox: triage unanswered incoming dialogues by urgency and priority.
• draft-reply: draft a customer response grounded in conversation history and tone.
• client-summary: summarize customer profile, past issues, and open topics.
• escalate-issue: generate a structured escalation packet for engineering or senior support.
• shift-handover: support shift handover report covering the backlog queue, channel health, and team availability.

Resources & Templates

Static Resources

• teletype://project/status: current project status, channel status, and balance.
• teletype://workspace/metadata: workspace channels, operators, groups, tags, and categories.
• teletype://dialogs/unanswered: current queue of unanswered customer dialogues with direct links.

Resource Templates

• teletype://dialogs/{dialogId}: full message history for a specific dialogue by ID.
• teletype://clients/{clientId}: client profile, tags, and notes by client ID.

Plugins for Claude Code, Codex, and Cursor

The repository contains marketplaces for Claude Code, Codex, and Cursor. The plugin/ directory includes .claude-plugin/plugin.json and .cursor-plugin/plugin.json, the portable Agent Plugins manifests plugin.json and mcp.json, the shared support skill, and commands. See the plugin README for configuration and data access.

Claude Code

The plugin bundles the hosted MCP server (https://mcp.teletype.app/mcp, authenticated with the X-Teletype-Api-Token header supplied by the plugin's sensitive configuration field), the teletype-support skill with the support workflows and safety rules, and five slash commands that mirror the server's MCP prompts: /triage-inbox, /draft-reply, /client-summary, /escalate-issue, /shift-handover.

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

/plugin install teletype@teletype-mcp-server

When enabling the plugin, enter the token in the Teletype Public API token field. This required sensitive userConfig field stores the value in Claude's secure credential store and supplies the HTTP header. Use an up-to-date Claude Code version with userConfig support. The skill carries the multi-step regulations that do not fit tool descriptions: triage order, dry-run before an ambiguous send, category lookup before closing. I