openbq-org/openbb/configure-mcp-server

Configure and Build the OpenBB MCP Server

This guide covers installation, configuration, authentication, tool discovery, prompt management, and client integration for openbb-mcp-server.

Installation

pip install openbb-mcp-server

This installs the openbb-mcp CLI command. To include the default OpenBB extensions as tools, also install them:

pip install openbb

Or install individual extensions:

pip install openbb-equity openbb-economy

The cli extra adds openbb-cli and its four dispatcher tools (openbb_dispatch, openbb_batch_dispatch, openbb_list_commands, openbb_describe_command); enable_cli_tools=false turns them off:

pip install "openbb-mcp-server[cli]"

Starting the Server

Default (all installed OpenBB extensions)

openbb-mcp

Defaults: --host 127.0.0.1 --port 8001 --transport streamable-http

With a Custom FastAPI Application

# File path with default instance name "app"
openbb-mcp --app ./my_app.py
 
# Explicit instance name
openbb-mcp --app ./my_app.py --name my_app
 
# Module import syntax
openbb-mcp --app my_package.app:my_app
 
# Factory function pattern
openbb-mcp --app ./my_app.py:create_app --factory

Transport Options

CLI Arguments

Every other --key value is routed by name: an MCPSettings field sets that setting (--enable-cli-tools false, --server-auth '["user", "pass"]'), --httpx-<option> sets an option of the httpx client that calls the API (--httpx-verify false), and anything else is passed to uvicorn (--log-level debug).

Spec-Driven Proxy Mode

Instead of importing a FastAPI app in-process, the launcher can synthesize one from an openbb-cli generated .spec file. Each command in the spec becomes a FastAPI route that proxies to the spec's recorded base_url. FastMCP walks those routes and exposes them as MCP tools — same tool surface as a normal --app install, but the heavy import openbb lives on the upstream server.

Generating a spec

The spec is produced by openbb-cli:

openbb --generate-spec --server https://api.example.com --output cli.spec

This fetches /openapi.json from the server and writes a precomputed .spec file with every command's URL path, method, parameter schema, and a content_sha256 integrity hash.

Single-spec launch

openbb-mcp --spec /etc/openbb/cli.spec

Or via TOML (--config-file openbb.toml):

[mcp.spec]
path = "/etc/openbb/cli.spec"
# Optional: override the spec's recorded base_url at deploy time.
base_url = "https://upstream.example.com"
# Optional: pinned SHA-256. When set, the launcher recomputes the spec's
# canonical-JSON hash and refuses to start unless it matches — protects
# against silent file drift when the spec is fetched at deploy time.
content_sha256 = "abc123..."
 
[mcp.spec.headers]
# Static headers injected on every proxied upstream request.
# ``$VAR`` / ``${VAR}`` are substituted from the current environment;
# entries with unresolved variables are skipped with a warning.
Authorization = "Bearer $OPENBB_UPSTREAM_TOKEN"
X-API-Key     = "$OPENBB_UPSTREAM_KEY"

--spec and --app are mutually exclusive.

Multi-spec mounting

Each [mcp.spec.NAME] subtable mounts an independent spec under its own prefix. FastMCP turns the union of all mounted routes into MCP tools; per-spec hooks fire on every tool dispatch into that spec's mount.

[mcp.spec.equity]
path = "/etc/openbb/equity.spec"
mount = "/equity"                          # optional; defaults to "/<name>"
content_sha256 = "abc..."
[mcp.spec.equity.headers]
Authorization = "Bearer $EQUITY_TOKEN"
[mcp.spec.equity.auth]
hooks = ["my_pkg.auth:equity_token_check"]
[mcp.spec.equity.middleware]
hooks = ["my_pkg.middleware:equity_rate_limit"]
 
[mcp.spec.crypto]
path = "/etc/openbb/crypto.spec"
[mcp.spec.crypto.headers]
X-API-Key = "$CRYPTO_KEY"

openbb.toml Cascade

The launcher reads the same layered TOML cascade openbb-core ships with, lowest priority first:

pyproject.toml [tool.openbb] (so [tool.openbb.mcp]) → user-global ~/.openbb_platform/openbb.toml
  → project openbb.toml (walking up from CWD) → --config-file PATH (explicit)

Every layer is optional, and .openbb.toml works in place of openbb.toml. --config-file (or OPENBB_MCP_CONFIG / OPENBB_API_CONFIG / OPENBB_CONFIG) is the highest-priority TOML layer. [mcp] values are applied like CLI flags: a CLI flag beats them, and they beat OPENBB_MCP_* environment variables. [env] entries never replace a variable already set in the shell or a .env file.

Top-level tables

Auth and middleware hooks

Both [mcp.auth] and [mcp.middleware] accept a hooks list of module:attr entry points. Each hook is a 2-arg async function async def hook(request, call_next) and is wrapped as a Middleware(BaseHTTPMiddleware, dispatch=fn) on the MCP server's ASGI stack.

[mcp.auth]
hooks = ["my_pkg.auth:bearer_token_check"]
 
[mcp.middleware]
hooks = ["my_pkg.middleware:rate_limit", "my_pkg.middleware:request_logger"]

Auth hooks register before middleware hooks; within each list, registration order matches TOML order. Per-spec hooks (under [mcp.spec.NAME.auth] / [mcp.spec.NAME.middleware]) are scoped to that spec's mounted sub-app. The top-level hooks wrap the HTTP transports (streamable-http, sse); the stdio transport has no HTTP stack, so they do not run there.

Env injection

[env]
OPENBB_MCP_HOST = "0.0.0.0"
# Values support shell-style $VAR / ${VAR} substitution.
OPENBB_GITHUB_TOKEN = "$GITHUB_TOKEN"

Useful in containers to inject OPENBB_* keys without shell exports. Any key already present in the real environment is preserved.

Configuration Precedence

Settings are resolved in this order (highest priority first):

1. CLI arguments — command-line flags
2. `[mcp]` table of the `openbb.toml` cascade — applied like CLI flags; --config-file PATH > project openbb.toml > user-global ~/.openbb_platform/openbb.toml > [tool.openbb.mcp] in pyproject.toml
3. Environment variables — OPENBB_MCP_ prefixed, including those set by [env]
4. JSON settings file — ~/.openbb_platform/mcp_settings.json, written with the defaults on first run
5. Defaults — built-in MCPSettings defaults

Config File Example

Create ~/.openbb_platform/mcp_settings.json:

{
    "name": "My MCP Server",
    "default_tool_categories": ["equity", "economy"],
    "enable_tool_discovery": false,
    "describe_responses": false,
    "system_prompt_file": "/path/to/system_prompt.txt",
    "server_prompts_file": "/path/to/prompts.json"
}

Environment Variables

All settings map to OPENBB_MCP_ prefixed environment variables:

OPENBB_MCP_NAME="My MCP Server"
OPENBB_MCP_DEFAULT_TOOL_CATEGORIES="equity,economy,crypto"
OPENBB_MCP_ENABLE_TOOL_DISCOVERY=true
OPENBB_MCP_SYSTEM_PROMPT_FILE="/path/to/prompt.txt"
OPENBB_MCP_SERVER_PROMPTS_FILE="/path/to/prompts.json"

Settings Reference

Server Identity

Tool Configuration

enable_cli_tools registers the openbb-cli dispatcher tools when openbb-cli is installed. mask_error_details hides exception details from clients.

Prompt Configuration

HTTP Transport

httpx_client_kwargs configures the httpx client that sends tool calls to the API (headers, timeout, TLS verification).

Duplicate Handling

Options: "warn", "error", "replace", "ignore"

Module Exclusion