MCP Integration
Balchemy exposes Hub agent capabilities through the Model Context Protocol (MCP). MCP is an adapter boundary, not a separate business-logic layer: calls still go through Balchemy authentication, scope, policy, audit, and trading execution paths.
Studio bot-scoped MCP is retired as a user-facing product. Use Hub agent MCP/API access from Hub Agents & Keys and agent detail flows.
Quick start
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 Hub. 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/jsonHub agent access
Use Hub agent MCP/API when the caller is an always-on trading agent.
The operator:
- Creates or resumes 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 activity, logs, runtime, and tool-call errors from Hub.
- Rotates or revokes access when deployments or operators change.
The old /hub/api-keys route redirects to /hub/agents, so key management
belongs to Hub Agents & Keys and agent detail.
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 trading runtime should not receive manage scope unless it truly needs management access.
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, and key scope.
POST /mcp/<publicId>
Authorization: Bearer <mcp-key>
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "tools-1",
"method": "tools/list"
}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": "agent_status",
"arguments": {}
}
}Trading tools require an appropriate scope and still pass through policy, risk, wallet, replay, approval, and execution checks.
Safety boundaries
MCP should not expose raw provider tools, hidden broad scans, wallet mutation, approvals, withdrawals, direct swap bypasses, or private backend surfaces.
Plain-message convenience routing must not send read-scope requests to raw portfolio, raw research, raw discovery, trade, approval, withdrawal, or wallet mutation internals.