Telegram MCP Bridge

A simple bridge to request human confirmation via Telegram from an MCP agent (like Antigravity).

Antigravity Configuration

To add this server to your Antigravity configuration (or any MCP client), use the following JSON block.

You need to replace:

• <ABSOLUTE_PATH> with the absolute path where you cloned this repository.

• <YOUR_VERCEL_URL> with your Vercel deployment URL (e.g., https://my-telegram-bot.vercel.app).

Explanation

This script (mcp-server.js) acts as a local proxy. The agent communicates with it via stdio (standard), and the script makes HTTP requests to your Vercel backend, managing the question delivery and the polling (active waiting) for the response.

Architecture

1. Agent (Local) → calls ask_telegram_confirmation

2. Local Proxy ( → calls POST /api/confirm on Vercel

3. Vercel → sends a message to the Telegram Bot

4. User → replies YES/NO on mobile

5. Telegram → calls the Webhook POST /api/webhook on Vercel

6. Vercel → saves the response in Redis (Upstash)

7. Local Proxy → receives the response by polling GET /api/confirm-status

8. Agent → receives the result "User replied: YES"

Installation and Deployment

1. Clone and Prepare

2. Configure Telegram

1. Talk to @BotFather to create a bot (/newbot).

2. Save the BOT_TOKEN.

3. Get your CHAT_ID (send a message to the bot and check https://api.telegram.org/bot<TOKEN>/getUpdates).

3. Deploy to Vercel

Configure environment variables in Vercel:

• BOT_TOKEN: Your Telegram token.

• CHAT_ID: Your chat ID.

• ALLOWED_USER_ID: Your numeric user ID (for security).

Configure Upstash Redis (from Vercel Marketplace) for persistence.

4. Configure Webhook

Once deployed, register the Telegram webhook using your Vercel URL:

Troubleshooting and Tips

1. Vercel "401 Unauthorized"

If the agent receives a 401 error, it's likely due to Vercel Deployment Protection.

• Go to your Vercel Dashboard → Settings → Deployment Protection.

• Disable "Vercel Authentication".

• This allows the local MCP proxy and Telegram webhooks to reach your API.

2. Forbidden (403)

Make sure the ALLOWED_USER_ID in your Vercel environment variables matches your actual Telegram User ID. You can find your ID by sending a message to @userinfobot.

3. State Persistence (Redis)

This bridge uses Redis to keep track of questions while waiting for your reply.

• Use the Vercel Marketplace to add Upstash Redis.

• Ensure it's Connected to your project in the Storage tab.

• We support both REST protocol (UPSTASH_REDIS_REST_URL) and standard Redis protocol (REDIS_URL).

• Redeploy your project after connecting the storage.

4. Continuous Polling (Wait state)

If the agent stays in a "Waiting" state even after you reply "YES":

• Check if Redis is correctly initialized by visiting https://<YOUR_VERCEL_URL>/health.

• You should see "redis_initialized": true.

5. Stable URLs

Always use the Production Domain (e.g., my-project.vercel.app) in your Antigravity configuration VERCEL_URL environment variable. Using the specific deployment URL (the one with the hash) will stop working after your next deploy.

How to use with an Agent

To trigger the confirmation, you just need to ask the agent in plain English (or Spanish). The agent will recognize that it needs to use the ask_telegram_confirmation tool.

Example Prompts:

• "Ask for my confirmation via Telegram before deleting any file."

• "Send me a confirmation request on Telegram to proceed with the deployment."

What happens next:

1. The agent will call the tool.

2. You will receive a message from your bot on Telegram: Should I proceed? Reply: YES / NO.

3. The agent will stay in a "waiting" state while polling Vercel.

4. Once you reply YES or NO on your phone, the agent will receive the answer and continue its task.