MCP Server
Use the bem MCP server to expose the bem API to Claude, Cursor, and other MCP-compatible agents
The bem MCP Server lets agents — Claude Desktop, Claude Code, Cursor, VS Code, and any other Model Context Protocol client — call the bem API on your behalf. It's published as bem-ai-sdk-mcp on npm.
What can bem's MCP Server do?
The bem MCP server runs in Code Mode: instead of exposing one tool per API endpoint, it exposes two general-purpose tools that together give the agent the full surface of the bem TypeScript SDK.
| Tool | What it does |
|---|---|
docs | Searches bem's API and SDK documentation. The agent uses this to discover what methods exist and how to call them. |
code | Executes TypeScript against the bem SDK in a sandbox with no network or filesystem access. Anything the code returns or prints comes back to the agent as the tool result. |
Because the agent writes real SDK code, it can do anything the SDK can do — manage functions and workflows, kick off calls, list events, configure subscriptions, query collections, manage API keys and environments — and chain those operations together in a single tool call.
Code Mode trades the discoverability of one-tool-per-endpoint for far greater capability and lower token cost. The agent learns the API by searching docs, then writes a single block of code instead of orchestrating dozens of tool calls.
Prerequisites
- A bem account and an API key generated from Settings → API Keys.
- Node.js 18 or later (the server runs via
npx). - An MCP-compatible client — Claude Desktop, Claude Code, Cursor, VS Code, or any other client.
How to use the MCP Server
The server supports two transports. Stdio is the default and the right choice for local clients on the same machine; HTTP is for hosting the server remotely or sharing it across multiple users.
Stdio Transport (Default)
Pick your client below. In every case the server is launched on demand by the client — no long-running process to manage.
Run the following in your terminal:
claude mcp add bem_ai_sdk_mcp_api \
--env BEM_API_KEY="your-api-key-here" \
-- npx -y bem-ai-sdk-mcpClaude Code writes the server entry to ~/.claude.json. Restart Claude Code to pick up the change.
Add the server to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"bem_ai_sdk_api": {
"command": "npx",
"args": ["-y", "bem-ai-sdk-mcp"],
"env": {
"BEM_API_KEY": "your-api-key-here"
}
}
}
}Restart Claude Desktop after saving.
Open Cursor Settings → Tools & MCP → New MCP Server and add the following to mcp.json:
{
"mcpServers": {
"bem_ai_sdk_api": {
"command": "npx",
"args": ["-y", "bem-ai-sdk-mcp"],
"env": {
"BEM_API_KEY": "your-api-key-here"
}
}
}
}Open the Command Palette and run MCP: Open User Configuration, then add:
{
"servers": {
"bem_ai_sdk_api": {
"command": "npx",
"args": ["-y", "bem-ai-sdk-mcp"],
"env": {
"BEM_API_KEY": "your-api-key-here"
}
}
}
}Most other MCP clients accept the same shape. Drop the snippet into whatever JSON config the client expects:
{
"mcpServers": {
"bem_ai_sdk_api": {
"command": "npx",
"args": ["-y", "bem-ai-sdk-mcp"],
"env": {
"BEM_API_KEY": "your-api-key-here"
}
}
}
}Refer to your client's documentation for the exact file path.
You can also invoke the server directly without a client, useful for sanity-checking your setup:
export BEM_API_KEY="your-api-key-here"
npx -y bem-ai-sdk-mcp@latestHTTP Transport
For remote hosting, start the server in HTTP mode. Authorization is sent per-request as the x-api-key header, so a single hosted instance can serve multiple users:
npx -y bem-ai-sdk-mcp --transport=http --port=3000Use --socket /path/to/socket instead of --port to listen on a Unix socket.
Point an MCP client at the running server:
{
"mcpServers": {
"bem_ai_sdk_api": {
"url": "http://localhost:3000",
"headers": {
"x-api-key": "your-api-key-here"
}
}
}
}Options
The server accepts the following flags. Every flag also has a matching environment variable prefixed with MCP_SERVER_ (for example, MCP_SERVER_TRANSPORT=http).
| Flag | Description |
|---|---|
--transport <stdio|http> | Transport to use. Defaults to stdio. |
--port <number> | Port to bind when using HTTP transport. Defaults to 3000. |
--socket <path> | Unix socket to bind when using HTTP transport. |
--tools <code|docs> | Explicitly enable a tool. Repeat to enable multiple. |
--no-tools <code|docs> | Explicitly disable a tool. Repeat to disable multiple. |
--code-execution-mode <stainless-sandbox|local> | Where the code tool runs. Defaults to stainless-sandbox. |
--code-allow-http-gets | Allow all SDK methods that map to HTTP GET operations. |
--code-allowed-methods <regex...> | Allowlist for SDK methods the code tool may call. |
--code-blocked-methods <regex...> | Blocklist for SDK methods the code tool may call. |
--docs-search-mode <stainless-api|local> | Where docs search runs. Defaults to stainless-api. |
--docs-dir <path> | Directory of additional markdown/JSON docs to include in local search. |
--custom-instructions-path <path> | Path to a file with custom instructions injected into the server's prompt. |
--log-format <json|pretty> | Log output format. Defaults to json (or pretty when stderr is a TTY). |
--debug | Enable debug logging. |
The required environment variable is BEM_API_KEY. When using the HTTP transport, the per-request x-api-key header takes precedence.
Local Development
To hack on the server itself, clone the TypeScript SDK monorepo and build the package:
git clone https://github.com/bem-team/bem-typescript-sdk.git
cd bem-typescript-sdk/packages/mcp-server
pnpm install
pnpm buildRun a local stdio server:
export BEM_API_KEY="your-api-key-here"
node dist/index.jsOr run it over HTTP:
node dist/index.js --transport=http --port=3000Inspect tool calls and responses live with the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsThe inspector opens a browser UI where you can list tools, fire calls by hand, and watch the JSON-RPC traffic — the fastest way to verify the server is wired up before pointing a real client at it.