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. It triggers on support tasks without a slash command. The five workflows also exist as MCP prompts for clients that show them. The commands cover the sessions where they are not shown.

Cursor

The native Cursor manifest connects to the hosted server and includes the shared skill and commands. For a marketplace installation, set TELETYPE_API_TOKEN under Plugins → Configure. To connect directly without a plugin, follow the Cursor setup guide.

Codex

Export TELETYPE_API_TOKEN in the shell before starting Codex. The bundled stdio server inherits it from the Codex process.

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

Then run /plugins in Codex, install teletype, and start a new session. The plugin adds the skill and the local stdio server (the Agent Plugins spec does not allow variable expansion in HTTP headers, so a per-user token cannot ship inside the plugin). To connect Codex to the hosted endpoint instead, add it to ~/.codex/config.toml:

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

Codex also reads skills without plugins from .agents/skills in the repository or ~/.agents/skills for the user.

Other agents

Install the support skill with the Skills CLI:

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

Select your agent and installation scope when prompted. This command installs the workflow instructions. Connect the MCP server separately using the client guide.

The skill uses the open Agent Skills format, supported by OpenCode, Cursor, Gemini CLI, GitHub Copilot, Goose, and others. The npm package ships the skill, so after a regular install:

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

CLI Usage

The server accepts CLI flags and environment variables:

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 and --toolsets <names> (comma-separated conversations,messaging,admin,meta) filter which tools the server registers before any client connects. get_capabilities always stays registered and reports the active map.

Requirements and local installation

• Node.js 20.19+, 22.13+, or 24.x for the packaged CLI.
• a Teletype Public API token from the project settings.

The same Node.js versions support the local npm start, npm run dev, and npm run eval:model scripts.

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

stdio transport

Use stdio for a local personal MCP client. The process reads the token from its environment. File uploads through attachment_path are disabled by default. To enable them, set ENABLE_LOCAL_UPLOADS=true and list the permitted directories in TELETYPE_ALLOWED_FILE_ROOTS. Use directories that other local users cannot write to.

Local build configuration:

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

Run it locally:

TRANSPORT=stdio TELETYPE_API_TOKEN=... npm start

Streamable HTTP transport

The hosted service at https://mcp.teletype.app uses this endpoint. The configuration below is for self-hosting.

The /mcp endpoint and stdio transport support both the 2025 initialize handshake and MCP 2026-07-28 server/discover. Both use the same tool definitions.

Endpoint: POST /mcp. Send the Teletype API token with every request in this header:

X-Teletype-Api-Token: <token>

Do not send the Teletype project token in Authorization. Use HTTPS for remote access. Anyone with the project token can access its data through the MCP server, subject to deployment restrictions.

OAuth is disabled on the public hosted endpoint at https://mcp.teletype.app/mcp. Connect with your project token in X-Teletype-Api-Token. For self-hosting, the code includes optional OAuth, disabled by default and enabled through separate configuration.

TRANSPORT=http HOST=127.0.0.1 PORT=4311 npm start

HTTP endpoints:

Each HTTP request gets its own MCP Server and transport pair, so concurrent tenants do not share responses or context. The server limits concurrent requests globally and per token. It returns 429 with Retry-After when a limit is reached. The HTTP transport cannot read local files.

Docker

The image runs as an unprivileged user and listens on port 4311 by default:

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

For a public domain, set its origin in PUBLIC_BASE_URL and terminate HTTPS at the reverse proxy.

For an MCP client that starts a container over stdio, build the stdio target and forward the token from your private environment. Keep stdin open with -i and omit -t, which would interfere with MCP messages:

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

The stdio target runs as the same unprivileged user and does not expose an HTTP port or use an HTTP health check. Set TELETYPE_MCP_READ_ONLY=true to disable write tools.

Configuration

PUBLIC_BASE_URL and each entry in ALLOWED_ORIGINS must be an origin without a path, query, or fragment. The server validates the value whenever a client sends an Origin header.

TELETYPE_MCP_LOCALE sets the language of MCP instructions, tool descriptions, prompts, hints, and server-generated errors. It applies to the whole server process, including all HTTP clients. Set it to ru in the MCP server environment for Russian text. Tool names, argument names, and structuredContent fields stay the same. Customer data and error details from Teletype keep their original language. The server does not infer the locale from the host OS or API token.

Troubleshooting

• Client cannot connect: run doctor --stdio with your token, then check the client transport settings.
• stdio transport requires TELETYPE_API_TOKEN: add the token to the client's server environment. The doctor checks only local configuration, not token validity.
• Tools missing from the client's list: run doctor --stdio and check its Mode and Toolsets lines, or call get_capabilities. --read-only and --toolsets hide tools at registration time.
• HTTP 401 or 403 from Teletype: check the token in Teletype project settings.
• A write timed out or was cancelled: check the conversation or project state before sending it again.

Development

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 checks the 2025 and 2026-07-28 handshakes over HTTP and stdio with the SDK client. The tests also check HTTP token isolation and reject tool results that break their outputSchema.

package:smoke installs the npm archive in a temporary directory and checks its CLI, exports, both protocol versions, and the eval fixture. mcp:conformance runs five short scenarios from the independent MCP conformance suite against a local server and fake Teletype API. Neither command contacts a Teletype project.

bundle:mcpb creates artifacts/teletype-mcp-server-v<version>.mcpb, validates its manifest, and checks the packaged server through MCP stdio. It does not contact Teletype.

Model compatibility eval

To run the eval through a terminal agent, connect it to the offline eval fixture. The agent uses MCP tools against fake Teletype data and can request separate outcome, first-attempt, answer, and safety metrics through eval_grade_case. No model API endpoint is required.

The eval results cover 21 complete tasks and nine tool-selection cases per terminal client, with token counts, duration, and estimated API-equivalent token cost.

The optional eval:model command runs the same checks through an OpenAI-compatible chat completions endpoint. It starts a local fake Teletype API and MCP server and needs no real project token or customer data.

Set an endpoint that provides OpenAI-compatible POST /chat/completions:

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

For a short check of tool descriptions, run npm run eval:selection > selection-report.json. It sends nine synthetic requests to the configured model and checks only the first tool chosen. No Teletype tool runs. A wrong or missing choice exits with code 2. This check does not measure whether the agent completes the task.

The eval checks:

• tool selection.
• required arguments and runtime validation.
• no write calls in read-only scenarios.
• confirmation before sending or closing.
• key result facts in the final answer.

Twenty-one scenarios run by default. EVAL_CASES selects a subset, and EVAL_THRESHOLD sets the passing score. Exit codes are 0 for a pass, 2 for a score below the threshold, and 1 for a configuration or runtime error. The JSON report goes to stdout and diagnostics go to stderr. The eval sends scenario text and fake API responses to the configured model endpoint.

The report also includes outcome, first-attempt, answer, and safety rates. Each scenario starts from a fresh fake project. A correction within one agent run counts toward the final outcome but does not change the first-attempt metric.

npm run check:fast runs formatting, linting, type checks, and tests. npm run check adds Knip, coverage thresholds, a 100% mutation score gate for request isolation and limiting, the build, and package checks with Publint and Are the Types Wrong.

npm run test:mutation runs the full mutation suite with a 33% score floor and writes reports to reports/mutation/. It takes longer and is not part of npm run check.

See SECURITY.md for vulnerability reporting and CONTRIBUTING.md for contribution guidelines. The project uses the MIT license.

Support and privacy

• Teletype help center
• Report a server issue
• Teletype privacy policy