Platform and MCP Settings

Two distinct settings groups that often get conflated: Platforms (where your bot talks) and MCP (how a human operator connects to your bot via an AI tool). This page covers both in full.

What is this?

The Platforms tab at /studio/bots/[botId]/platforms shows four channel cards — Telegram, Discord, X, and Web Widget. Each card has a connect toggle and a Configure button that opens a settings sheet. The MCP tab at /studio/bots/[botId]/mcp is where you issue API keys so that external MCP clients (like Claude Desktop) can invoke your bot's tools.

Prerequisites

• A bot in Running or Ready state
• For Telegram: the bot added to a Telegram group or channel using the Balchemy shared adapter
• For Discord: the Balchemy bot application authorized in your Discord server
• For MCP: an MCP-compatible client (Claude Desktop, or any OpenAI-compatible MCP client)

The single-channel rule

A Studio bot can only be set as the primary channel for one messaging platform at a time. You can connect multiple platforms (for example, Telegram + Discord), but only one can hold the primary designation for routing. This prevents split-brain routing where two channels send conflicting commands to the same trading engine.

Tip: If you need separate bots for Telegram and Discord with independent trading contexts, create two bots. The single-channel rule applies per-bot, not per-account.

Platform connections

Each platform card on the Platforms tab shows:

• Platform icon and name
• A toggle switch (Connected / Disconnected / Error)
• A status badge showing when it was last connected
• A Configure button for platform-specific settings

Toggle switches use optimistic updates — the UI immediately reflects your change, and rolls back if the API call fails with an error toast.

Step-by-step: connect a platform

1. Go to Studio → Bots → [your bot] → Platforms.
2. Find the platform card you want to connect.
3. Toggle the switch to Connected.
4. Click Configure to open the settings sheet.
5. Fill in the required fields (described per-platform below).
6. Save the settings sheet.
7. Verify the status badge shows Connected and a timestamp.

Telegram

Balchemy uses a central Telegram adapter. You do not provide a bot token. Instead, you configure who can interact with your bot and how.

Telegram settings

Access Mode explained:

• private — only the owner username can interact with the bot
• public — anyone who can find or add the bot can message it
• whitelist — only the usernames in the Allowed Usernames list can interact

Warning: Never set access mode to public if you have "Enable natural language trading" turned on in Config. Anyone in the world could potentially send trade commands to your bot.

Step-by-step: configure Telegram

1. Open the Telegram card and click Configure.
2. Set Access Mode to whitelist for most secure setup.
3. Add the Telegram usernames of people allowed to use the bot.
4. Set Only Respond to Mentions to On if you are adding the bot to a group chat.
5. Save the settings sheet.
6. Add the Balchemy Telegram bot handle to your group or start a DM with it.

Discord

Discord uses the Balchemy shared bot application. You authorize it in your server, then configure server-specific policy.

Discord settings

Step-by-step: configure Discord

1. Authorize the Balchemy bot app in your Discord server at discord.com/oauth2/authorize (link available in the Settings sheet).
2. Open the Discord card and click Configure.
3. Enter your Guild ID (right-click your server name in Discord → Copy Server ID).
4. Set Allowed Channels to the specific channels you want the bot active in.
5. Set Required Roles if you want to restrict bot access to specific roles.
6. Toggle Only Respond to Mentions if the bot is in a busy server.
7. Save the settings sheet.

X (Twitter/X)

X integration connects your bot to an X account for tweet monitoring and reply automation. Configuration requires an X API v2 developer application.

The X card's Configure button opens a settings sheet with fields for your X developer API credentials. This platform is best suited for market sentiment monitoring and automated reply bots, not trading execution.

X (Twitter) Configuration

1. Navigate to Platforms tab in Bot Cockpit
2. Toggle X Integration on
3. Configure:
   • Monitoring Keywords: Comma-separated terms the bot watches for in mentions and timeline
   • Reply Mode: Auto-reply to mentions, or manual approval
   • Sentiment Analysis: Bot analyzes market sentiment from tracked accounts
4. The bot monitors your timeline and mentions for trading signals and market discussion
5. Trading execution from X is disabled by default — enable via the Allow Trade Commands toggle

Note: X integration requires a valid X API key configured by the platform operator.

Web Widget

The Web Widget card on the Platforms tab shows connection status for your embedded widget. The detailed widget configuration (branding, domains, embed code) lives in the dedicated Widget tab. See Web Widget Integration for the full guide.

Toggling the Web Widget card on/off in the Platforms tab enables or disables the widget service endpoint globally for this bot. Even if the widget is configured in the Widget tab, it will not serve requests when this toggle is off.

MCP settings

The MCP tab at /studio/bots/[botId]/mcp has four sub-tabs: API Keys, Tools, Agent Card, and Logs.

When to use MCP

Use MCP when a human operator wants to connect an AI tool (Claude Desktop, Cursor, an OpenAI-compatible MCP client) to Balchemy and interact through natural language. The MCP layer exposes your bot's tools — all 106+ of them — as callable functions.

MCP is not the right choice when the actor is an external autonomous AI agent that discovers Balchemy through identity discovery. That scenario belongs to Hub. See Studio vs Hub for a full comparison.

Quick reference

API Keys (MCP sub-tab)

Key scopes

Always use the minimum scope needed. A key used only to fetch portfolio data should be read. Only issue manage-scoped keys to trusted automation that needs configuration-level access.

Step-by-step: create an MCP API key

1. Go to Studio → Bots → [your bot] → MCP.
2. Click Create Key.
3. Enter a descriptive name (e.g., "Claude Desktop – read only").
4. Select the scope (read, trade, or manage).
5. Click Create Key.
6. Copy the full key immediately. It is shown only once and cannot be retrieved after you dismiss the dialog.
7. Save the key in a password manager or secret store.

Warning: The full API key is shown only at creation time. If you lose it, you must revoke the old key and create a new one. There is no way to view the key again after dismissing the creation dialog.

Revoking a key

1. Find the key in the API Keys list.
2. Click the trash icon on the right.
3. Confirm in the dialog.

Revoked keys stop working immediately. There is no grace period.

Using the key with Claude Desktop

Add a server entry to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "balchemy": {
      "command": "npx",
      "args": ["-y", "@balchemy/mcp-server"],
      "env": {
        "BALCHEMY_API_KEY": "your-key-here",
        "BALCHEMY_BOT_ID": "your-bot-id"
      }
    }
  }
}

Restart Claude Desktop after saving the config file.

Tools (MCP sub-tab)

The Tools tab shows all tools available to MCP clients for this bot. Tools are grouped by scope:

Use the search box to filter tools by name, category, or description. Click any tool row to expand its description. Tools shown as Disabled cannot be called even with a valid key of the appropriate scope — they may be disabled at the platform level or require additional configuration.

Agent Card (MCP sub-tab)

The Agent Card is a JSON document at a public URL that describes your bot to external systems following the ERC-8004 agent discovery standard. It includes the bot's name, capabilities, tool count, and the MCP server endpoint.

Your agent card URL follows this pattern:

https://api.balchemy.ai/api/public/agents/{botId}/agent-card.json

Click Preview Card to open the JSON in a new tab. Click Publish Card to regenerate and publish the card with your current configuration. You should republish after adding new tools, changing scope, or updating the bot's public description.

Logs (MCP sub-tab)

The Logs tab shows operation logs for all MCP calls made through this bot. Each entry is a JSON object showing the tool called, the scope used, the timestamp, and the result status. Logs are useful for debugging MCP client integration issues and auditing which tools are being called.

Common issues

The Telegram card shows "Error" status. The Balchemy adapter could not connect to the Telegram API. This usually means the bot was removed from the group or the group was deleted. Re-add the Balchemy bot handle to your Telegram group, then toggle the connection off and back on.

Discord bot is not responding in my server. Check that the Guild ID in the Discord settings sheet matches your actual server ID. Also verify that the Allowed Channels list includes the channel you are testing in (or is empty to allow all channels).

I lost my MCP API key. Revoke the old key from the API Keys list and create a new one. Keep new keys in a password manager immediately after creation.

Claude Desktop cannot find the Balchemy server. Verify the claude_desktop_config.json file is valid JSON, that the BALCHEMY_BOT_ID matches your actual bot ID, and that the key has not been revoked. Check the MCP Logs tab for error entries.

Related pages

• Studio Bot Cockpit
• Bot AI Configuration
• Web Widget Integration
• Hub External Agents
• MCP Integration
• ERC-8004 Agent Identity