BOARDHERALDDocs
// agents.configuration

Configuration

The nuts and bolts — key issuance, the bridge, env-var alternatives, and when (not) to self-host.

Getting an API key

  1. Sign in at https://app.boardherald.com (or, if you have a white-label subdomain or custom domain like board.acme.com, sign in there).
  2. Open Profile → API Keys.
  3. Click New key, pick a persona (see Capabilities), give it a descriptive name ("claude-desktop-laptop", "morning-brief-cron"), generate.
  4. Copy the bh_… value. It's shown exactly once.

Don't see the menu? The MCP surface is plan-gated. Contact support to upgrade your plan.

The bridge

@boardherald/mcp-bridge is a ~110-line Node script that reads JSON-RPC messages from stdin, forwards each as a POST to your tenant's /api/mcp endpoint, and writes the HTTP response back to stdout. That's it — no state, no dependencies, no telemetry.

It exists because Claude Desktop (and some other clients) currently speaks MCP over stdio only. The bridge is the translator. ChatGPT and custom clients that speak remote MCP natively can skip the bridge entirely and hit /api/mcp directly.

Source, license, versions: github.com/getbananalabs/boardherald-mcp. Open source under MIT — clone it, audit it, self-host it.

Environment variables

Instead of passing --api-key and --url on the command line, you can set env vars. Useful for CI / systemd / launchd contexts where putting secrets on argv is a no-go.

shell
BOARDHERALD_API_KEY=bh_REPLACE_WITH_YOUR_KEY \
BOARDHERALD_URL=https://app.boardherald.com \
  npx -y @boardherald/mcp-bridge

Supported env vars:

  • BOARDHERALD_API_KEY — equivalent to --api-key. Command-line flag wins if both are set.
  • BOARDHERALD_URL — equivalent to --url. Same precedence.

Protocol version

BoardHerald implements MCP version 2025-11-25. Clients that negotiate a different version will get an explicit error frame rather than silently broken tool calls. If your client doesn't let you pin a protocol version, the bridge handles it transparently.

Self-hosting the bridge

If your security posture requires running only audited code, clone the repo and invoke the script directly:

shell
git clone https://github.com/getbananalabs/boardherald-mcp.git
cd boardherald-mcp
node scripts/mcp-bridge.mjs \
  --api-key bh_REPLACE_WITH_YOUR_KEY \
  --url https://app.boardherald.com

Then point your MCP client's command at node and args at the absolute path to scripts/mcp-bridge.mjs instead of using npx.

Pin the version in prod
For production agents, pin the bridge version (e.g. @boardherald/mcp-bridge@0.1.0) instead of using the unpinned -y install. New bridge versions are additive but pinning protects you from surprise behaviour.