Workspace MCP Quickstart

This guide starts the Workspace MCP sidecar on your machine, connects it to an OpenBB Workspace browser tab, and configures an MCP client to call Workspace tools.

Prerequisites

Before you start:

• OpenBB Workspace is available in your browser.
• Your MCP client supports HTTP MCP servers.
• Your machine can run Python 3.13.
• You can install or run tools with uv.

The helper script installs uv when it is missing. If you manage Python environments manually, install uv first and use the direct command shown below.

1. Start the sidecar

Install the sidecar from the Workspace MCP repository, or use one of the one-line installers below.

macOS, Linux, WSL, and Git Bash:

curl -LsSf https://raw.githubusercontent.com/OpenBB-finance/workspace-mcp/main/scripts/run.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -Command "Invoke-RestMethod https://raw.githubusercontent.com/OpenBB-finance/workspace-mcp/main/scripts/run.ps1 | Invoke-Expression"

The default server listens on:

http://127.0.0.1:8787

The MCP endpoint is:

http://127.0.0.1:8787/mcp

The script installs uv if needed, then runs workspace-mcp from the OpenBB Workspace MCP source archive.

For advanced options (custom host/port, forks, branches, or local checkouts), see the Workspace MCP repository.

2. Check sidecar health

In another terminal, call the health endpoint:

curl http://127.0.0.1:8787/health

Before Workspace connects, the response should show that the sidecar is running and no browser is attached:

{
  "ok": true,
  "browser_connected": false,
  "pending_commands": 0,
  "session": null
}

After Workspace connects, browser_connected should be true and session should include the current browser session metadata.

3. Connect Workspace to the sidecar

Open OpenBB Workspace in your browser and connect the local companion:

1. Open Workspace.
2. Click the hamburger icon in the top-left corner.
3. Open Workspace MCP Companion.

4. Set the companion base URL to http://127.0.0.1:8787.
5. Click the connect action after the sidecar is running.

By default, the sidecar allows CORS requests from https://pro.openbb.co and loopback origins such as http://localhost:1420 and http://127.0.0.1:1420.

For a different Workspace origin, pass --cors-allow:

workspace-mcp --cors-allow https://example.openbb.dev

Repeat --cors-allow or pass a comma-separated list to allow more than one origin:

workspace-mcp \
  --cors-allow https://one.example.openbb.dev,https://two.example.openbb.dev \
  --cors-allow http://localhost:1420

4. Configure your MCP client

Point your MCP client at:

http://127.0.0.1:8787/mcp

For clients that read a project .mcp.json file, use an HTTP server entry:

{
  "mcpServers": {
    "workspace_mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}

If your client has an mcp add command or settings UI, choose the HTTP transport and use the same /mcp URL.

For Codex:

codex mcp add workspace_mcp --url http://127.0.0.1:8787/mcp

For Claude Code:

claude mcp add --transport http workspace_mcp http://127.0.0.1:8787/mcp

5. Validate the connection

Ask the agent to call get_workspace_snapshot. A successful call should return the active Workspace state, including dashboard metadata and the current dashboard composition when available.

A practical validation prompt is:

Call get_workspace_snapshot and tell me the active dashboard id and the visible tabs.

If the agent can list the dashboard and tabs, the MCP client, sidecar, and browser bridge are connected.

6. Try common Workspace actions

After the connection is working, ask the agent to read data from Workspace or add a widget to the current dashboard. The agent should inspect the live Workspace state first, then call the relevant MCP tools with identifiers from the snapshot.

For reading data, use a prompt like:

What data do you see on this dashboard and tab?

For adding a widget, use a prompt like:

Analyze my current portfolio exposure and add a markdown note widget with that analysis in the same tab that is open

Configuration reference

Option	Default	Description
--host	127.0.0.1	Host interface for the sidecar HTTP server. Keep this on loopback for normal use.
--port	8787	Port for the sidecar HTTP server.
--mcp-path	/mcp	Path for the streamable HTTP MCP endpoint.
--command-timeout-seconds	15.0	Seconds to wait for one browser command result.
--cors-allow	production Workspace and loopback origins	Extra browser origins allowed to call the sidecar.
--reload	disabled	Restart the local development server when source files change.

In reload mode, the CLI also maps options to OPENBB_WORKSPACE_MCP_* environment variables so Uvicorn can recreate the app.

Troubleshooting

Symptom	What to check
No Workspace browser is connected.	Open Workspace, open Workspace MCP Companion, and connect it to the sidecar base URL.
browser_connected is false in /health	The sidecar is running, but the browser bridge has not connected or has disconnected.
Browser CORS error	Add the Workspace browser origin with --cors-allow.
Tool call times out	Keep the Workspace tab open and active enough to execute commands. Increase --command-timeout-seconds for slower operations.
MCP client cannot connect	Confirm the client supports HTTP MCP servers and uses http://127.0.0.1:8787/mcp, not the sidecar base URL.