openbb-finance/openbb/work-with-server
Claude Code and agent skill by openbb-finance/openbb
- community
Checking that the SKILL.md file is still in the repository.
This guide explains how to call tools, interpret responses, discover capabilities, use prompts, and handle errors when interacting with an OpenBB MCP server.
Install
npx vskill@latest install openbb-finance/openbb/work-with-serverSKILL.md
The same SKILL.md was published earlier as openbb-finance/openbb/work-with-server.
Working With the OpenBB MCP Server
This guide explains how to call tools, interpret responses, discover capabilities, use prompts, and handle errors when interacting with an OpenBB MCP server.
Tool Discovery Workflow
When the server runs with --tool-discovery, the OpenBB tools are left out of the tool list, and a small set of discovery tools finds and runs them.
Discovery holds no per-session state — every client sees the same tool list, and nothing needs to be activated before a call.
Step 1 — List Categories
Call available_categories (no arguments) to see what is installed:
Each category maps to a top-level API router. Subcategories are nested routers.
Step 2 — Browse Tools in a Category
Call available_tools with a category name:
Each entry has the tool's name and a one-sentence description. The subcategory argument is optional. Omit it to see all tools in the category.
Step 3 — Search for Tools
Call search_tools with a natural-language query:
Search covers the hidden OpenBB tools and returns at most five matches. Use each match's inputSchema to build the arguments.
Step 4 — Call a Tool
Call call_tool with the tool name and its arguments:
call_tool runs the named tool and returns its result. A hidden tool can also be called directly by name, with the same arguments.
When Discovery Is Disabled
If the server was started without --tool-discovery, the discovery tools are not available. All tools in default_tool_categories are listed and called directly; tools outside them are not served, and calling one fails with "Unknown tool".
openbb-cli Dispatcher Tools
When the optional openbb-mcp-server[cli] extra is installed (it pulls in openbb-cli), the server also registers four first-class tools that wrap openbb-cli's NDJSON dispatcher protocol. They give an agent the same obb-namespace command surface that the openbb CLI exposes — without shelling out or standing up a Python REPL.
openbb_dispatch
Execute a single command and return its serialized result.
| Argument | Type | Notes | ||
|---|---|---|---|---|
command | string | Dotted command path under the obb namespace (e.g. equity.price.historical). | ||
params | `dict \ | null` | Keyword arguments forwarded to the command. Defaults to {}. | |
server_url | `string \ | null` | When set, dispatches against a remote openbb-platform-api server (HTTP). When omitted, falls back to OPENBB_SERVER_URL, then in-process local dispatch. |
The result is a dispatcher response. ok reports success, result holds the command's OBBject fields (results, provider, ...), and error carries the type and message of a failure instead of raising:
Remote dispatch unwraps a single-row results list to the row itself.
openbb_batch_dispatch
Execute many commands concurrently and return results in input order.
Each entry needs command (dotted path); params and id are optional. The id is opaque correlation echoed back on the matching response. Failures surface as response objects with ok=False and a structured error block — no exception bubbles up, errors are per-request.
openbb_list_commands
List every command with a one-line description. Takes only the optional server_url. The response's result is a list of {"name", "description"} entries. Equivalent to openbb --list-commands on the CLI.
openbb_describe_command
Return one command's parameters and output schema.
The response's result has the command name, its parameters (each with name, in, and type, plus required, default, choices, and help when set), and its output_schema. For a command with several providers, pass provider to get that provider's parameters and output_schema; without it, result.providers maps every provider to its own parameters and output_schema. Equivalent to openbb --describe equity.price.historical (equity.price.historical:yfinance for one provider) on the CLI.
Local vs remote dispatch
| Mode | Trigger | Behavior | |
|---|---|---|---|
| Local | No server_url, no OPENBB_SERVER_URL | LocalDispatcher resolves commands against the in-process obb namespace. Pays the heavy import openbb once at startup. Single-tenant. | |
| Remote | server_url arg or OPENBB_SERVER_URL env | HttpDispatcher proxies commands to a long-running openbb-platform-api server. Multi-tenant; the heavy import lives on the server. |
Mode is per-call — different requests in the same session can target different servers. Dispatchers are cached for the server's lifetime, so the import openbb cost (local) and the remote server's OpenAPI download are paid once per target.
Calling Data Tools
Input Parameters
Every data tool has a JSON Schema describing its input. A typical tool schema:
Key rules:
- `provider` — present only on endpoints that use the provider interface.
When listed, its enum shows available provider sources. If the endpoint has only one provider, you can omit it and the sole provider is used automatically. When multiple providers are available, select one from the enum. Different providers may return different fields or support different parameters. Endpoints that do not use the provider interface (basic GET/POST routes) have no provider parameter at all.
- `symbol` formatting — symbols are case-insensitive. Multiple symbols can
be comma-separated: "AAPL,MSFT,GOOG".
- Dates — always formatted as
YYYY-MM-DDstrings. - Optional parameters — have
anyOfwith anulltype or adefault
value. Omit them to use defaults.
- Provider-specific parameters — some parameters are only relevant for
certain providers. The schema unions all of them; irrelevant ones are silently ignored.
- Valid values — never guess a value. A parameter with a fixed set of
values has an enum. When the values differ by provider, or several can be comma-separated, the description lists them (Valid values by provider: ..., Valid values for provider oecd (comma-separate several): ...). When another tool lists them, the description names it and its arguments (`Get the valid values from the derivatives_options_strikes tool with symbol=<the symbol you pass here>.`) — call that tool first.
Example Tool Call
Understanding the Response
Every OpenBB tool returns an OBBject — a standardized response envelope:
Response Fields
| Field | Type | Description | ||||
|---|---|---|---|---|---|---|
id | string | UUID identifying this request | ||||
results | `list[dict] \ | dict \ | string \ | null` | The actual data. Usually a list of records | |
provider | `string \ | null` | Which provider fulfilled the request | |||
warnings | `list[object] \ | null` | Non-fatal warnings from the provider or platform | |||
chart | `object \ | null` | Chart artifact if chart=true was passed | |||
extra | dict | Execution metadata and results metadata |
The results Field
This is the primary data payload. Its structure depends on the endpoint:
Tabular data — most common, a list of dictionaries (one per row):
Single record — some endpoints return a single dict:
Empty results — when no data is available:
or
Field names vary by provider — different providers may return different columns for the same endpoint. Always check the keys in the returned records.
The warnings Field
Warnings are non-fatal issues that occurred during execution:
Common warning scenarios:
- Unknown parameters silently ignored by the provider
- Partial data returned (fewer rows than requested)
- Provider-specific data quality notes
When warnings is null, no warnings were generated.
The extra Field
Contains execution metadata and optional results metadata:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingopenbb_platform/extensions/mcp_server/openbb_mcp_server/skills/work_with_server/SKILL.md
Popularity
- Repository stars
- 70,028
- Repository forks
- 7,083
- 7-day trend score
- 56
Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 4 Jul 2026, 4 months ago.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/openbb-finance/openbb/work-with-server)