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: