MCP Integration

Balchemy exposes bot and agent capabilities through the Model Context Protocol (MCP). MCP is a protocol surface, not a separate business-logic layer: tool calls still go through Balchemy's authentication, scope, policy, audit, and trading execution paths.

Use MCP in one of two product contexts:

Context	Managed from	Best for
Studio bot MCP	Studio bot cockpit MCP tab	A human operator or MCP client calling one Balchemy bot.
Hub agent MCP/API	Hub → Agents & Keys / agent detail	A 24/7 Web3 agent with identity, funding, scopes, logs, and monitoring.

Quick start — MCP client

Add the Balchemy MCP endpoint and bearer key to an MCP-compatible client:

{
  "mcpServers": {
    "balchemy": {
      "transport": "http",
      "url": "https://api.balchemy.ai/mcp/<publicId>",
      "headers": {
        "Authorization": "Bearer <mcp-key>"
      }
    }
  }
}

Replace <publicId> and <mcp-key> with values shown by the relevant Studio or Hub flow. Do not guess IDs from URLs or logs.

After connecting, call MCP tools/list to see the exact tools visible to the current key and scope.

Endpoint

POST https://api.balchemy.ai/mcp/<publicId>
Authorization: Bearer <mcp-key-or-token>
Content-Type: application/json

The /mcp prefix is intentionally outside the /api namespace so MCP clients can address it directly.

Two MCP contexts

Studio bot MCP

Use Studio bot MCP when a client should operate one Studio bot. This is common for operator workflows around a personal bot, community bot, Telegram/Discord bot, or web-widget bot.

The operator:

Opens the bot cockpit in Studio.
Goes to the MCP tab.
Creates a bot-scoped key with the minimum required scope.
Copies the secret immediately; full keys are shown once.
Adds the endpoint and key to the MCP client.
Calls tools/list to confirm visible capabilities.

Studio MCP keys belong to the bot context. They are different from Hub agent keys.

Hub agent MCP/API

Use Hub agent MCP/API when the caller is an always-on Web3 agent. Hub adds the agent operations layer: identity, funding, scoped access, logs, monitoring, and key rotation.

The operator:

Registers or onboards the agent.
Stores the one-time key securely.
Funds the agent wallet only if the agent will trade.
Assigns the minimum scope needed.
Connects the MCP/API client.
Monitors logs and tool-call errors from Hub.
Rotates or revokes access when deployments or operators change.

See Hub Overview, Agent Keys, and ERC-8004 Agent Identity.

Authentication

Studio bot key

POST /mcp/<publicId>
Authorization: Bearer <studio-bot-mcp-key>
Content-Type: application/json

Create and revoke Studio bot keys from the bot cockpit MCP tab.

Hub agent key or token

POST /mcp/<publicId>
Authorization: Bearer <hub-agent-key-or-token>
Content-Type: application/json

Manage Hub agent keys from Hub → Agents & Keys and the agent detail flow. The old /hub/api-keys route redirects to /hub/agents, so do not treat it as the primary key management page.

Some agent identity flows issue short-lived scoped tokens. Token lifetime depends on scope and identity context.

Scope model

MCP access uses a three-level scope hierarchy:

Scope	Use it for	Safety expectation
`read`	Status, logs, portfolio, research, and read-only calls.	Observe only.
`trade`	Trading commands and mutable trade workflows allowed by policy.	Fund-sensitive; risk checks apply.
`manage`	Sensitive management actions such as key rotation or configuration changes.	Keep rare; step-up or ownership checks may apply.

Use the smallest scope that works. A monitoring client should not receive a trade key. A trade automation should not receive manage scope unless it truly needs configuration control.

MCP scopes are permissions, not pricing plans.

Tool discovery

Do not rely on a hardcoded tool count or a static catalog. The visible tools depend on:

Runtime registry state.
Environment configuration.
Principal context.
Key type.
Key scope.

Use tools/list with the current key as the source of truth.

POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
 
{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "method": "tools/list"
}

The response includes the tool names, descriptions, and input schemas visible to that caller.

Standard tool call

POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
 
{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "ask_bot",
    "arguments": {
      "message": "Summarize my current portfolio and open risk.",
      "chat_id": "session-abc123"
    }
  }
}

Trading tools require an appropriate scope and still pass through policy, risk, wallet, and execution checks.

Manage-sensitive actions

Manage-sensitive actions can require additional verification such as owner/claim or step-up style checks. Do not put manage keys into unattended runtimes unless the runtime truly needs management access.

Examples of sensitive actions include:

Rotating or revoking keys.
Changing scopes.
Updating sensitive agent configuration.
Ownership or claim-sensitive flows.

Prefer creating a separate short-lived or tightly controlled path for those actions instead of reusing a trading runtime key.

Rate limits and reliability controls

Balchemy may enforce application, MCP, and AI usage limits to protect reliability. These limits are not paid access tiers.

When a caller exceeds a limit, reduce request volume or retry after the indicated window. For programmatic integrations, prefer direct scoped tool calls over repeatedly routing every operation through a conversational step.

Audit and safety

MCP calls are designed to be auditable and scope-aware. Depending on key type and runtime configuration, calls can be checked for:

Bearer authentication.
Key or token scope.
Origin restrictions.
Replay or nonce protections.
Rate limits.
Tool safety profile.
Policy and risk checks.
Redacted audit logging.

Do not log full keys, tokens, private keys, seed phrases, or full authorization headers.

Common issues

The client connects but no trade tools are visible. The key may be read scoped, the environment may expose a limited tool set, or the principal context may not allow those tools. Call tools/list with the same key.

A tool returns forbidden. The key scope may be too low, the tool may require a management check, or a policy/risk rule may block the action.

The key used to work but now fails. It may have been revoked, rotated, expired, or pointed at the wrong publicId. Create a new key from the correct Studio or Hub flow.

I created a Hub key but expected it to control a Studio bot. Hub keys are agent-level. For a Studio bot, create a bot-scoped MCP key from the bot cockpit MCP tab.

Web Widget

ERC-8004

Edit this page on GitHub

MCP Integration

Use MCP in one of two product contexts:

Context	Managed from	Best for
Studio bot MCP	Studio bot cockpit MCP tab	A human operator or MCP client calling one Balchemy bot.
Hub agent MCP/API	Hub → Agents & Keys / agent detail	A 24/7 Web3 agent with identity, funding, scopes, logs, and monitoring.

Quick start — MCP client

Add the Balchemy MCP endpoint and bearer key to an MCP-compatible client:

{
  "mcpServers": {
    "balchemy": {
      "transport": "http",
      "url": "https://api.balchemy.ai/mcp/<publicId>",
      "headers": {
        "Authorization": "Bearer <mcp-key>"
      }
    }
  }
}

Replace <publicId> and <mcp-key> with values shown by the relevant Studio or Hub flow. Do not guess IDs from URLs or logs.

After connecting, call MCP tools/list to see the exact tools visible to the current key and scope.

Endpoint

POST https://api.balchemy.ai/mcp/<publicId>
Authorization: Bearer <mcp-key-or-token>
Content-Type: application/json

The /mcp prefix is intentionally outside the /api namespace so MCP clients can address it directly.

Two MCP contexts

Studio bot MCP

Use Studio bot MCP when a client should operate one Studio bot. This is common for operator workflows around a personal bot, community bot, Telegram/Discord bot, or web-widget bot.

The operator:

Opens the bot cockpit in Studio.
Goes to the MCP tab.
Creates a bot-scoped key with the minimum required scope.
Copies the secret immediately; full keys are shown once.
Adds the endpoint and key to the MCP client.
Calls tools/list to confirm visible capabilities.

Studio MCP keys belong to the bot context. They are different from Hub agent keys.

Hub agent MCP/API

Use Hub agent MCP/API when the caller is an always-on Web3 agent. Hub adds the agent operations layer: identity, funding, scoped access, logs, monitoring, and key rotation.

The operator:

Registers or onboards the agent.
Stores the one-time key securely.
Funds the agent wallet only if the agent will trade.
Assigns the minimum scope needed.
Connects the MCP/API client.
Monitors logs and tool-call errors from Hub.
Rotates or revokes access when deployments or operators change.

See Hub Overview, Agent Keys, and ERC-8004 Agent Identity.

Authentication

Studio bot key

POST /mcp/<publicId>
Authorization: Bearer <studio-bot-mcp-key>
Content-Type: application/json

Create and revoke Studio bot keys from the bot cockpit MCP tab.

Hub agent key or token

POST /mcp/<publicId>
Authorization: Bearer <hub-agent-key-or-token>
Content-Type: application/json

Manage Hub agent keys from Hub → Agents & Keys and the agent detail flow. The old /hub/api-keys route redirects to /hub/agents, so do not treat it as the primary key management page.

Some agent identity flows issue short-lived scoped tokens. Token lifetime depends on scope and identity context.

Scope model

MCP access uses a three-level scope hierarchy:

Scope	Use it for	Safety expectation
`read`	Status, logs, portfolio, research, and read-only calls.	Observe only.
`trade`	Trading commands and mutable trade workflows allowed by policy.	Fund-sensitive; risk checks apply.
`manage`	Sensitive management actions such as key rotation or configuration changes.	Keep rare; step-up or ownership checks may apply.

Use the smallest scope that works. A monitoring client should not receive a trade key. A trade automation should not receive manage scope unless it truly needs configuration control.

MCP scopes are permissions, not pricing plans.

Tool discovery

Do not rely on a hardcoded tool count or a static catalog. The visible tools depend on:

Runtime registry state.
Environment configuration.
Principal context.
Key type.
Key scope.

Use tools/list with the current key as the source of truth.

POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
 
{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "method": "tools/list"
}

The response includes the tool names, descriptions, and input schemas visible to that caller.

Standard tool call

POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
 
{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "ask_bot",
    "arguments": {
      "message": "Summarize my current portfolio and open risk.",
      "chat_id": "session-abc123"
    }
  }
}

Trading tools require an appropriate scope and still pass through policy, risk, wallet, and execution checks.

Manage-sensitive actions

Examples of sensitive actions include:

Rotating or revoking keys.
Changing scopes.
Updating sensitive agent configuration.
Ownership or claim-sensitive flows.

Prefer creating a separate short-lived or tightly controlled path for those actions instead of reusing a trading runtime key.

Rate limits and reliability controls

Balchemy may enforce application, MCP, and AI usage limits to protect reliability. These limits are not paid access tiers.

Audit and safety

MCP calls are designed to be auditable and scope-aware. Depending on key type and runtime configuration, calls can be checked for:

Bearer authentication.
Key or token scope.
Origin restrictions.
Replay or nonce protections.
Rate limits.
Tool safety profile.
Policy and risk checks.
Redacted audit logging.

Do not log full keys, tokens, private keys, seed phrases, or full authorization headers.

Common issues

A tool returns forbidden. The key scope may be too low, the tool may require a management check, or a policy/risk rule may block the action.

The key used to work but now fails. It may have been revoked, rotated, expired, or pointed at the wrong publicId. Create a new key from the correct Studio or Hub flow.

I created a Hub key but expected it to control a Studio bot. Hub keys are agent-level. For a Studio bot, create a bot-scoped MCP key from the bot cockpit MCP tab.

Web Widget

ERC-8004

Edit this page on GitHub