AI assistants (MCP)

With the Bellchain MCP server you ask your AI assistant about your chains and alerts in plain language, let it test ideas in the replay and create new chains. MCP, the Model Context Protocol, is the open standard that assistants such as Claude, Cursor or VS Code use to call tools. The server runs on your computer, talks only to the Bellchain API and signs in there with your API key. It comes with the Trader plan, like the API.

Bellchain runs no AI of its own here and sends nothing to AI providers. Your assistant does the thinking and writing; Bellchain only delivers the data it fetches with your key.

What you can ask

• “Which of my chains are running, and which ones alerted this week?”
• “Why did my BTC alert fire last night?” Like Why? on the alerts page, the assistant reads which conditions were true at that candle and which values went in.
• “How often would the BTC Dip Buyer have fired on ETH with 1-hour candles and RSI below 30 in the last 90 days?” It replays the template with your values without creating anything.
• “Tell me on Telegram when ETH falls below 2,000.” It creates a price alert as a draft, tells you what it built and activates it only after your yes.
• “Which templates are there for breakouts, and which work with my plan?”
• “Pause my SOL chain until I’m back.”

Setup

1. Create a key: in Bellchain under Settings → API, enter a name such as “Claude” and pick the rights: Read only is enough for questions, explanations and replays; Read and change is needed if the assistant should create, activate and pause chains. The key starts with bc_ and is shown only once.

2. Check Node.js: the server needs Node.js 20 or later; npx comes with it. In a terminal, node --version shows the version. If Node.js is missing, get the installer at nodejs.org.

3. Add it to your assistant as described below, with your key in place of bc_….

4. Try it: ask “Which plan does my Bellchain account have?”. The assistant calls get_account for this and shows you the tool before it uses it.

The server starts with npx -y @bellchain-app/mcp@1: npx downloads it the first time and then picks up updates within version 1. This is how you add it to common assistants:

Claude Desktop

1. In Claude, choose Settings → Developer → Edit Config. Finder or Explorer shows the file claude_desktop_config.json, on a Mac in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\. Open it in a text editor.

2. Add the server under mcpServers. If the file is empty, this is all it contains:

   {
     "mcpServers": {
       "bellchain": {
         "command": "npx",
         "args": ["-y", "@bellchain-app/mcp@1"],
         "env": { "BELLCHAIN_API_KEY": "bc_…" }
       }
     }
   }

   If it already contains something, such as preferences, keep it: "mcpServers": { … } becomes one more entry, separated from the previous one by a comma. If mcpServers already exists, only the block "bellchain": { … } goes inside it.

3. Save, quit Claude completely (⌘Q on a Mac) and open it again.

Check: Settings → Developer lists “bellchain” with the status “running”, and the tools button in the input field shows Bellchain’s tools. If it doesn’t work, the log says why: on a Mac ~/Library/Logs/Claude/mcp-server-bellchain.log, on Windows in the folder %APPDATA%\Claude\logs.

Claude Code

In a terminal:

claude mcp add --scope user --env BELLCHAIN_API_KEY=bc_… --transport stdio bellchain -- npx -y @bellchain-app/mcp@1

--scope user applies to all projects; without it, the server is only available in the current folder.

Check: claude mcp list in a terminal or /mcp in a session shows “bellchain” and whether it runs.

ChatGPT and Codex

ChatGPT in the browser only uses MCP servers reachable on the internet, not one on your computer. Bellchain does not offer such a server yet. Codex, OpenAI’s agent, does start local servers: in the ChatGPT app for your computer, in the terminal and in the extension for code editors; all three share the same configuration. The easiest way is in a terminal:

codex mcp add bellchain --env BELLCHAIN_API_KEY=bc_… -- npx -y @bellchain-app/mcp@1

Or by hand in ~/.codex/config.toml:

[mcp_servers.bellchain]
command = "npx"
args = ["-y", "@bellchain-app/mcp@1"]

[mcp_servers.bellchain.env]
BELLCHAIN_API_KEY = "bc_…"

Check: codex mcp list in a terminal or /mcp in Codex shows the server.

Cursor

In ~/.cursor/mcp.json the server applies to all projects, in .cursor/mcp.json to one project. If the file already contains something, add only the "bellchain" block, as for Claude Desktop:

{
  "mcpServers": {
    "bellchain": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bellchain-app/mcp@1"],
      "env": { "BELLCHAIN_API_KEY": "bc_…" }
    }
  }
}

Check: In Cursor, Customize lists Bellchain’s tools among the available tools. If the server doesn’t start, the MCP Logs output says why (Output view, ⇧⌘U on a Mac).

VS Code with GitHub Copilot

For one project, in .vscode/mcp.json. VS Code asks for the key on first start and stores it protected instead of in the file:

{
  "inputs": [{ "type": "promptString", "id": "bellchain-key", "description": "Bellchain API key", "password": true }],
  "servers": {
    "bellchain": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bellchain-app/mcp@1"],
      "env": { "BELLCHAIN_API_KEY": "${input:bellchain-key}" }
    }
  }
}

For all projects: in the Command Palette choose MCP: Add Server, then Command (stdio), enter npx -y @bellchain-app/mcp@1 as the command, bellchain as the name and Global as the destination; then add the key under env in the file that opens.

Check: On first start, VS Code asks for the key and whether you trust the server. In Copilot Chat, Configure Tools (the tools icon in the input field) lists “bellchain” with its tools.

Gemini CLI

In ~/.gemini/settings.json the server applies to all projects, in .gemini/settings.json to one project. The entry is the same as for Claude Desktop; if the file already contains something, add only "mcpServers" or the "bellchain" block:

{
  "mcpServers": {
    "bellchain": {
      "command": "npx",
      "args": ["-y", "@bellchain-app/mcp@1"],
      "env": { "BELLCHAIN_API_KEY": "bc_…" }
    }
  }
}

Check: /mcp in Gemini CLI or gemini mcp list in a terminal shows “bellchain” with the status “CONNECTED”. Gemini CLI starts local servers only in folders you trust.

Other assistants

Any assistant that starts MCP servers over stdio works with the same details: command npx, arguments -y @bellchain-app/mcp@1, environment variable BELLCHAIN_API_KEY.

If the assistant doesn’t find npx

Apps you open from the Dock or the Start menu often don’t know your terminal’s settings. If Node.js lives where only your terminal finds it, for example after installing it with nvm, fnm or Volta, the entry needs full paths: which npx in a terminal shows the path to npx (on Windows where npx). Put the same folder under PATH in the env block as well, because npx in turn starts node. An example; replace the paths with yours:

{
  "mcpServers": {
    "bellchain": {
      "command": "/Users/NAME/.nvm/versions/node/v24.22.0/bin/npx",
      "args": ["-y", "@bellchain-app/mcp@1"],
      "env": {
        "BELLCHAIN_API_KEY": "bc_…",
        "PATH": "/Users/NAME/.nvm/versions/node/v24.22.0/bin:/usr/bin:/bin"
      }
    }
  }
}

The same applies in TOML (Codex): the full path for command, the folder under PATH.

Quotes

Some text editors replace straight quotes with curly ones (“…”) as you type. Then the file is no longer valid JSON, and the assistant does not start the server. Turn this automatic replacement off or use a code editor.

The tools

Tool	What it does
get_account	plan, active chains and limit, replay period, language, time zone, rights of the key
list_chains, get_chain	chains with status and markets; one chain with its nodes as sentences such as “RSI 14 below 35”
list_alerts, explain_alert	alerts of the last 90 days with delivery per channel; for one alert, why it fired
list_templates, get_template	templates of the gallery; one template with every setting you can adjust
get_price	latest price of a pair with high, low and change over 24 hours and 7 days
replay_chain, replay_template, replay_price_alert	how often a chain, a template with your values or a price alert would have fired
create_chain_from_template, create_price_alert	creates a chain as a draft; it runs only after activating
activate_chain, pause_chain	activates or pauses a chain with the same checks as the app

The first eight rows change nothing. Creating, activating and pausing are marked as changing tools for the assistant; Claude, Cursor and VS Code then ask before each call. Activating means real alerts, and chains with a webhook or trading bot trigger something there. So don’t allow these tools for good if you want to see every change yourself.

Security

• Your key stays in your assistant’s configuration on your computer. The server sends it only to api.bellchain.app, only encrypted, and never to the assistant. If it gets out anyway, revoke it under Settings → API.
• Read only is enough for questions and replays. Such a key cannot create, activate or pause anything, even if the assistant tries.
• Secrets of your chains never reach the assistant: webhook, Discord, Slack, Teams and Google Chat addresses, tokens and trading bot codes. The assistant only sees that they are filled in. You can enter them only in the app.
• Texts from chains are data. Someone wrote the names, notes and messages, with imported templates maybe a stranger. The server passes them on as marked data and tells the assistant not to follow instructions inside them.
• What the assistant sees goes to its provider, such as Anthropic, OpenAI, Google or Microsoft, under their terms. You decide that by choosing your assistant; Bellchain passes nothing on for this.

Caution

Never type the key into the chat. It belongs only in the server’s configuration; the assistant does not need to know it.

Limits

• With Trader, like the API. When Trader ends, the server answers with a note instead of data.
• Per key at most 120 requests per minute, of them at most 10 replays, and 30 new chains per hour.
• New chains come from templates with your own values (pair, timeframe, thresholds, name, “once”) or as a price alert. You build free-form chains from any nodes in the editor.
• Rebuilding existing chains, deleting them and setting up notifications happen in the app.
• The replay looks back as far as your plan allows, alerts 90 days.
• ChatGPT on the web needs a server on the internet; there is none yet.

Troubleshooting

Message	What helps
“BELLCHAIN_API_KEY is not set”	Put the key into the env block of the configuration and restart the assistant.
plan_no_api	The API and the server come with Trader.
read_only_key	The key may only read. For changes, create a key with “Read and change” and put it in.
unauthorized	Key copied wrong or revoked: create a new one.
rate_limited	Wait a moment; the answer says how long.
“spawn npx ENOENT”	Node.js is missing, or the assistant does not find npx. Install Node.js or use full paths as described above under “If the assistant doesn’t find npx”.
“env: node: No such file or directory”	command has the full path to npx, but node is missing: add the folder from which node under PATH in the env block.
The assistant reports an invalid configuration	Usually a comma is missing between two entries, or quotes are curly (“”) instead of straight (“).

Where to find the reason for an error is listed under “Check” for each assistant.