TeleBotHost MCP Server

A Model Context Protocol server for the TeleBotHost Developer API — 68 tools to manage Telegram bots from AI assistants like Claude, Cursor, and Copilot.

Features

• 68 Tools — Full coverage of the TeleBotHost Developer API + 3 docs search tools

• Multi-Platform — Deploys on Vercel, Render, Railway, Fly.io, or any Node host

• Secure — Bearer token auth, optional MCP endpoint protection, key-tier awareness (sk_* vs pub_*)

• Resilient — Automatic 429 retry with exponential backoff, rate-limit header tracking

• Binary-Safe — Base64-encoded ZIP download/upload for download_bot and import_bot

• Safe by Design — Broadcast tool requires explicit confirm: true flag

• Tested — Compliance test suite verifies MCP spec adherence (scripts/test-mcp.sh)

• Type-Safe — Strict TypeScript throughout, clean compile

• Zero-Config — Single env var (TELEBOTHOST_API_KEY) to get started

Related MCP server: agent-telegram-mcp

Table of Contents

• Architecture

• Quick Start

• Deployment

  • Vercel

  • Render

  • Railway / Fly.io / Self-Host

• Connecting Your AI Client

• Available Tools (68)

• MCP Protocol

• Error Handling

• Testing

• API Coverage

• Environment Variables

• Rate Limits

• Local Development

• Project Structure

• Roadmap

• Contributing

• License

Architecture

┌─────────────────┐      POST /api/mcp       ┌─────────────────────┐      Bearer sk_*      ┌─────────────────────┐
│                 │      JSON-RPC 2.0        │  MCP Server         │      HTTPS            │  TeleBotHost API    │
│  Claude Desktop │  ───────────────────▶   │  (stateless)        │  ───────────────────▶ │  api.telebothost.com│
│  Cursor         │                          │  68 tools           │                       │                     │
│  Continue       │  ◀───────────────────   │  JSON-RPC router    │  ◀─────────────────── │  64 endpoints       │
│  Cline          │      JSON response      │  TBH API client     │      JSON             │                     │
└─────────────────┘                          └─────────────────────┘                       └─────────────────────┘
                                                      │
                                                      ▼
                                             ┌─────────────────┐
                                             │  Vercel         │  ← api/mcp.ts (serverless)
                                             │  OR Render      │  ← server.ts (Node HTTP)
                                             │  OR Railway     │
                                             │  OR Fly.io      │
                                             └─────────────────┘

Transport: Streamable HTTP (stateless JSON-RPC 2.0 over HTTP POST) Runtime: Node.js 20+ · TypeScript 5.7 · @modelcontextprotocol/sdk 1.x

Quick Start

1. Get your TeleBotHost API key

1. Log in to TeleBotHost

2. Go to Developer Settings → API Keys

3. Generate a key:

   • sk_* — Secret key (full write access) — keep private

   • pub_* — Public key (read-only) — safe for client-side

2. Deploy (pick a platform)

3. Connect your AI client

See Connecting Your AI Client below.

Deployment

Vercel (Recommended)

One-click deploy:

Manual deploy:

# Clone
git clone https://github.com/telebothost/mcp-server.git
cd telebothost-mcp
npm install

# Set env var
vercel env add TELEBOTHOST_API_KEY production
# Paste your sk_* key when prompted

# Deploy
vercel --prod

Your MCP endpoint: https://your-project.vercel.app/api/mcp

Render

This repo includes a render.yaml blueprint.

Option A — Dashboard (easiest):

1. Push this repo to your GitHub

2. Go to Render Dashboard → New → Blueprint

3. Select your repo — Render auto-detects render.yaml

4. Add TELEBOTHOST_API_KEY as a secret env var

5. Click Apply

Option B — CLI:

# Install Render CLI
npm i -g @render-ai/render-cli

# Link & deploy
render blueprint deploy

Your MCP endpoint: https://telebothost-mcp.onrender.com/api/mcp

Railway / Fly.io / Self-Host

These platforms use the generic Node server (server.ts) via npm start.

# Clone & install
git clone https://github.com/telebothost/mcp-server.git
cd telebothost-mcp
npm install

# Set env vars
export TELEBOTHOST_API_KEY=sk_your_key_here
# Optional: export MCP_AUTH_TOKEN=your_mcp_protection_token

# Start
npm start
# → [telebothost-mcp v1.0.0] MCP server listening on :3000

Railway:

railway init
railway up
# Set TELEBOTHOST_API_KEY in Railway dashboard

Fly.io:

fly launch --no-deploy
fly secrets set TELEBOTHOST_API_KEY=sk_your_key_here
fly deploy

Docker (any host):

docker build -t telebothost-mcp .
docker run -p 3000:3000 -e TELEBOTHOST_API_KEY=sk_xxx telebothost-mcp

Note: Create a Dockerfile if you need container builds — the Node server is runtime-agnostic.

Connecting Your AI Client

Once deployed, point any MCP-compatible client at your endpoint. Pass your TeleBotHost API key in the X-Tbh-Api-Key header so each call uses your own TBH quota — the server never stores your key.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telebothost": {
      "url": "https://your-deployed-url/api/mcp",
      "transport": "http",
      "headers": {
        "X-Tbh-Api-Key": "sk_your_telebothost_key_here"
      }
    }
  }
}

Cursor

Settings → MCP → Add Server:

{
  "mcpServers": {
    "telebothost": {
      "url": "https://your-deployed-url/api/mcp",
      "headers": {
        "X-Tbh-Api-Key": "sk_your_telebothost_key_here"
      }
    }
  }
}

VS Code (with Cline / Continue)

Add to your MCP settings:

{
  "mcp.servers": {
    "telebothost": {
      "url": "https://your-deployed-url/api/mcp",
      "headers": {
        "X-Tbh-Api-Key": "sk_your_telebothost_key_here"
      }
    }
  }
}

With MCP_AUTH_TOKEN protection (server-side access control)

If the server has MCP_AUTH_TOKEN set (to restrict WHO can call the MCP), add both headers:

{
  "mcpServers": {
    "telebothost": {
      "url": "https://your-deployed-url/api/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-auth-token",
        "X-Tbh-Api-Key": "sk_your_telebothost_key_here"
      }
    }
  }
}

• Authorization: Bearer ... → authenticates you to the MCP server (the MCP_AUTH_TOKEN)

• X-Tbh-Api-Key: ... → your TeleBotHost API key (forwarded to TBH API)

Test with curl

# List all tools (no TBH key needed)
curl -X POST https://your-deployed-url/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a public tool (no TBH key needed)
curl -X POST https://your-deployed-url/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_status","arguments":{}}}'

# Call an authenticated tool (pass your TBH key)
curl -X POST https://your-deployed-url/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-Tbh-Api-Key: sk_your_key_here" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_bots","arguments":{}}}'

API Key Resolution (Priority Order)

When a tools/call request arrives, the server resolves the TBH API key in this order:

Best practice: Don't set TELEBOTHOST_API_KEY on the server. Let each client pass X-Tbh-Api-Key so everyone uses their own TBH quota.

Available Tools (68)

Health (1)

Public Discovery (9) — no auth required

Bot Lifecycle (20) — sk_* key required for writes

Bot Storage (4)

Broadcasts (6)

Commands (13) — full CRUD + folder management

Environment Variables (5)

Logs & Analytics (3)

Community Store (2)

Quota (1)

Docs Search (3) — no auth required

MCP Protocol

This server implements the Model Context Protocol Streamable HTTP transport in stateless mode — perfect for serverless platforms.

JSON-RPC 2.0 Methods Supported

Stateless Design

Each HTTP request creates a fresh server instance — no session persistence, no in-memory state. This means:

• Works on Vercel serverless, AWS Lambda, Cloudflare Workers

• Horizontally scalable (any number of replicas)

• No cold-start session affinity issues

• No server-initiated notifications (clients must poll)

• No SSE streaming (single JSON response per request)

Request/Response Format

Request:

POST /api/mcp HTTP/1.1
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_bots",
    "arguments": {}
  }
}

Success response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{...bot data as JSON...}" }]
  }
}

Error response (tool-level):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "TeleBotHost API error 403: ..." }],
    "isError": true
  }
}

Error response (protocol-level):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32601, "message": "Method not found: foo/bar" }
}

Error Handling

The server implements a layered error handling strategy:

Layer 1: Protocol Errors (JSON-RPC)

Returned as {error: {code, message}} per the JSON-RPC 2.0 spec:

Layer 2: Tool Errors (MCP isError)

When a tool executes but the upstream TBH API returns an error, the response includes isError: true with the error details in the content text field. The AI client can read this and decide how to proceed (retry, ask user, etc.).

{
  "content": [{
    "type": "text",
    "text": "TeleBotHost API error 429: Rate limit exceeded. Retry after 60s."
  }],
  "isError": true
}

Layer 3: Automatic Retry

HTTP 429 responses from the TBH API are automatically retried up to 3 times with exponential backoff:

After 3 retries, the 429 is surfaced as a tool error.

Layer 4: Cloudflare Detection

The TBH API is behind Cloudflare, which may challenge datacenter IPs. The client detects Cloudflare challenge responses (HTTP 403 + cf_chl in body) and returns a user-friendly message instead of the raw HTML challenge page.

Testing

Compliance Test Suite

The repo includes a bash-based compliance test suite that verifies MCP spec adherence:

# Test against local server
npm start &
sleep 2
MCP_URL=http://localhost:3000/api/mcp ./scripts/test-mcp.sh

# Test against production
MCP_URL=https://tbh-mcp.vercel.app/api/mcp ./scripts/test-mcp.sh

# With auth token
MCP_URL=https://your-url/api/mcp MCP_TOKEN=xxx ./scripts/test-mcp.sh

What it verifies:

1. initialize handshake returns correct protocol version & server info

2. ping returns a result

3. tools/list returns exactly 68 tools

4. All tools have name + description + inputSchema

5. All tools use clean names (no telebothost_ prefix)

6. tools/call rejects unknown tools with error -32602

7. Invalid JSON returns -32700 parse error

8. GET method returns HTTP 405 (only POST allowed)

9. All required tools are present (10 critical tools checked)

Type Safety

npm run typecheck
# → tsc --noEmit (strict mode, zero errors)

Manual Smoke Test

# Initialize
curl -X POST $MCP_URL -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# List tools
curl -X POST $MCP_URL -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST $MCP_URL -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_status","arguments":{}}}'

API Coverage

This MCP server covers 100% of the TeleBotHost Developer API — every endpoint in the OpenAPI 3.0.3 spec is mapped to a tool.

Binary Endpoints (Expert Implementation)

Two endpoints involve binary data (ZIP files) which MCP's JSON model doesn't natively support. They're handled via base64 encoding:

Example download_bot response:

{
  "success": true,
  "content_type": "application/zip",
  "filename": "my-bot.zip",
  "size_bytes": 4523,
  "size_kb": 4.42,
  "encoding": "base64",
  "base64": "UEsDBBQACAgA..."
}

The AI client can then write the base64 to a file and decode it to get the actual ZIP.

Environment Variables

Two Layers of Auth (Important!)

This MCP has two independent auth layers — don't confuse them:

Typical setups:

1. Public MCP, per-user TBH keys (recommended for shared deployments):

   • Don't set MCP_AUTH_TOKEN, don't set TELEBOTHOST_API_KEY

   • Each client passes X-Tbh-Api-Key: sk_their_own_key in their MCP config

   • Server stores no secrets

2. Protected MCP, per-user TBH keys (recommended for team deployments):

   • Set MCP_AUTH_TOKEN on server

   • Don't set TELEBOTHOST_API_KEY

   • Clients pass both Authorization: Bearer <mcp_token> AND X-Tbh-Api-Key: sk_their_own_key

3. Personal MCP, server-side key (simplest for solo use):

   • Set TELEBOTHOST_API_KEY on server

   • Don't set MCP_AUTH_TOKEN

   • Clients don't need any headers (server uses its env var for all calls)

Rate Limits

The TeleBotHost API enforces plan-based limits. This MCP server automatically retries on HTTP 429 with exponential backoff (up to 3 retries).

pub_* keys are always capped at 1,000/day, 15/min, 15,000/month regardless of plan.

Use get_quota to check remaining quota at any time.

Local Development

# Install deps
npm install

# Set env vars
cp .env.example .env
# Edit .env with your TELEBOTHOST_API_KEY

# Run locally (generic Node server)
npm run dev
# → http://localhost:3000/api/mcp

# OR run as Vercel dev (simulates serverless)
npm run vercel:dev

# Type-check
npm run typecheck

# Test
curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Project Structure

telebothost-mcp/
├── api/
│   ├── index.ts            # GET /         → Docs page (root)
│   ├── docs.ts             # GET /docs     → Docs page (alias)
│   ├── health.ts           # GET /api/health → JSON health probe
│   └── mcp.ts              # POST /api/mcp → MCP JSON-RPC endpoint
├── lib/
│   ├── types.ts            # Shared types & TbhApiError
│   ├── client.ts           # TeleBotHost API client (auth, retry, binary, errors)
│   ├── tools.ts            # All 68 MCP tool definitions
│   └── docs.ts             # HTML docs page generator
├── scripts/
│   └── test-mcp.sh         # Compliance test suite
├── server.ts               # Generic Node HTTP server (Render/Railway/Fly)
├── render.yaml             # Render.com Blueprint config
├── vercel.json             # Vercel serverless config + routes
├── .env.example            # Environment variable template
├── .nvmrc                  # Node version pin
├── package.json
├── tsconfig.json
├── LICENSE
├── CONTRIBUTING.md
└── README.md

Endpoints

Roadmap

• v1.0.0 — Initial release: 46 tools, Vercel deployment

• v1.1.0 — Cleaner tool names (dropped telebothost_ prefix)

• v1.2.0 — 100% API coverage: download_bot & import_bot (binary base64), compliance test suite, multi-platform deploy configs

• v1.3.0 — Per-request API key via X-Tbh-Api-Key header — multi-user support, each user uses own TBH quota

• v2.0.0 — 68 tools: full CRUD for commands + folders, env vars, logs, analytics, docs search (TBH API, TBL lang, Telegram Bot API)

• v2.1.0 — Docker support, GitHub Actions CI, automated coverage check in CI

• v2.2.0 — SSE streaming transport for stateful deployments (Render/Railway)

• v3.0.0 — Tool-level RBAC, audit logging, multi-region deployment guide

Contributing

Contributions welcome! See CONTRIBUTING.md for setup, conventions, and PR guidelines.

Adding a new tool

1. Open lib/tools.ts

2. Add a ToolDef to the appropriate group

3. Use a clear snake_case name, short description, JSON-Schema input

4. Run npm run typecheck

5. Open a PR

Acknowledgements

Special thanks to Cyber (@CyberXCoding) for creating the base version of this MCP server that this project was built upon.

License

MIT © Muiz Ahmed (mmuizahmed)

Links

• TeleBotHost: telebothost.com

• Developer API Docs: api.telebothost.com/api/v1/docs

• MCP Specification: modelcontextprotocol.io

• GitHub: github.com/telebothost/mcp-server

• Issues: GitHub Issues

Built for the TeleBotHost community by Muiz Ahmed