Skip to content

Commit 5ed9638

Browse files
DidierRLopesDidierRLopes
committed
add workspace mcp docs
1 parent 0f393b6 commit 5ed9638

11 files changed

Lines changed: 2221 additions & 9 deletions

File tree

‎content/agents/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Agents",
3+
"position": 2
4+
}

‎content/agents/workspace-mcp-overview.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Workspace MCP Overview
3+
sidebar_position: 1
4+
description: Understand how the OpenBB Workspace MCP exposes a live Workspace browser session to external AI agents.
5+
keywords:
6+
- OpenBB Workspace MCP
7+
- Model Context Protocol
8+
- MCP server
9+
- AI agents
10+
- Workspace Companion
11+
- dashboard automation
12+
---
13+
14+
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
15+
import TutorialVideo from '@site/src/components/General/TutorialVideo.tsx';
16+
17+
<HeadTitle title="Workspace MCP Overview | OpenBB Docs" />
18+
19+
The OpenBB Workspace MCP is a local companion server that exposes your active Workspace browser session as Model Context Protocol (MCP) tools. An external MCP-capable agent can use those tools to inspect dashboards, fetch widget data, create widgets, manage tabs, register backends, and instantiate Workspace apps.
20+
21+
Use it when an agent needs structured access to Workspace state. It avoids brittle browser automation because the agent calls Workspace commands directly instead of clicking through the UI.
22+
23+
## How it differs from MCP tools inside Workspace
24+
25+
OpenBB Workspace supports MCP in two directions:
26+
27+
| Feature | Direction | Main use case |
28+
|---------|-----------|---------------|
29+
| Workspace MCP | External agent to Workspace | Let Codex, Claude Code, Cursor, a custom agent, or another MCP client control a live Workspace session. |
30+
| MCP tools in Copilot | Workspace to external MCP servers | Let Workspace Copilot call tools from third-party MCP servers. |
31+
32+
The Workspace MCP is the first case. Workspace becomes the tool server, and your agent becomes the client.
33+
34+
## Demo in Codex
35+
36+
This demo shows Codex using the Workspace MCP to interact with an active OpenBB Workspace session.
37+
38+
<TutorialVideo
39+
youtubeLink="https://www.youtube.com/embed/Q4Pj9wMZgGs"
40+
/>
41+
42+
## Architecture
43+
44+
The Workspace MCP runs as a local sidecar process:
45+
46+
```text
47+
MCP client or agent
48+
|
49+
| streamable HTTP MCP
50+
v
51+
Workspace MCP sidecar
52+
|
53+
| WebSocket bridge
54+
v
55+
OpenBB Workspace browser tab
56+
|
57+
| Workspace frontend state and backend calls
58+
v
59+
Dashboards, widgets, apps, data backends, and skills
60+
```
61+
62+
The sidecar exposes a stateless MCP endpoint at `http://127.0.0.1:8787/mcp` by default. Workspace connects to the same sidecar through a browser bridge. Tool calls sent by the agent are forwarded to the connected browser tab, executed by Workspace, and returned as structured results.
63+
64+
The browser must stay open and connected. If the Workspace tab disconnects, the sidecar remains running but tool calls return an unavailable error until the browser reconnects.
65+
66+
## What agents can do
67+
68+
The current tool surface covers the main Workspace authoring and inspection workflows:
69+
70+
| Area | Examples |
71+
|------|----------|
72+
| Session discovery | Read the current Workspace state, active dashboard, tabs, layout coordinates, available skills, and connected tools. |
73+
| Widget discovery | List widgets from connected backends, inspect widget schemas, and fetch dynamic parameter options. |
74+
| Data access | Fetch live widget data using the same data path the Workspace renderer uses. |
75+
| Dashboard authoring | Create, read, and rename dashboards; navigate between dashboards and tabs. |
76+
| Tab management | Create a navigation bar, add tabs, remove tabs, and rename tabs. |
77+
| Widget authoring | Create widgets from backend definitions, update widget parameters, resize or move widgets, read widget state, and delete individual widgets. |
78+
| Generated artifacts | Add generated notes, tables, charts, and HTML widgets without a backend connection. |
79+
| Backend and app workflows | Register data backends, refresh backends, list app templates, and instantiate apps into dashboards. |
80+
| Agent and skill workflows | Delegate tasks to configured Workspace agents and load skills from the Workspace skill library. |
81+
82+
The MCP server also publishes app-builder resources under `openbb://workspace/...`. Agents can read these resources when they are building or reviewing Workspace backends, `widgets.json`, or `apps.json` files.
83+
84+
## Common workflows
85+
86+
### Build a dashboard from live Workspace state
87+
88+
A typical dashboard workflow starts with `get_workspace_snapshot`, then uses identifiers from that response:
89+
90+
1. Read the active dashboard and available backends.
91+
2. Create or select a dashboard.
92+
3. Add tabs with `manage_navigation_bar`.
93+
4. List widgets with `list_available_widgets`.
94+
5. Inspect the exact widget contract with `get_widget_schema`.
95+
6. Create widgets with explicit `origin`, `widget_id`, and `data_args`.
96+
7. Use `update_widget_layout` to place widgets on the 40-column grid.
97+
98+
Agents should not invent dashboard IDs, widget IDs, tab IDs, backend IDs, or skill slugs. They should discover those values through the MCP tools and reuse them.
99+
100+
### Build and open a custom app
101+
102+
The Workspace MCP can close the loop for agent-built Workspace apps:
103+
104+
1. The agent creates or modifies a backend that serves `widgets.json` and, when needed, `apps.json`.
105+
2. The agent registers the backend with `manage_backends`.
106+
3. The agent lists app templates with `manage_apps`.
107+
4. The agent instantiates an app into a dashboard with `manage_apps`.
108+
5. The agent validates rendered widgets with `get_workspace_snapshot`, `manage_dashboard`, and `get_widget_data`.
109+
6. The agent edits the backend or widget parameters and tests again.
110+
111+
This is useful for development workflows where the agent owns both the backend code and the Workspace dashboard used to validate it.
112+
113+
## Trust and security model
114+
115+
Treat any MCP client connected to the Workspace MCP as trusted. The tool server can read Workspace state and mutate dashboards in the connected browser session.
116+
117+
Keep the sidecar local:
118+
119+
- Bind to `127.0.0.1`, which is the default.
120+
- Do not expose it on `0.0.0.0`, a LAN address, a tunnel, or a public reverse proxy.
121+
- Use local HTTP for `localhost` or `127.0.0.1`; HTTPS is not required for the local sidecar.
122+
- Connect only MCP clients you trust to read and change your Workspace.
123+
124+
The Workspace MCP operates inside an existing authenticated browser session. It does not log in for you, manage authentication tokens, change billing, change organization settings, invite users, or share dashboards.
125+
126+
## Requirements
127+
128+
- An OpenBB Workspace browser tab.
129+
- The Workspace MCP sidecar running locally.
130+
- An MCP client that can connect to a streamable HTTP MCP server.
131+
- Python 3.13 when installing or running the sidecar directly.
132+
- `uv` for the recommended install path. The helper script installs `uv` if it is not already available.
133+
134+
See [Workspace MCP Quickstart](/agents/workspace-mcp-quickstart) for setup steps and [Workspace MCP Tools](/agents/workspace-mcp-tools) for the tool reference.

0 commit comments

Comments
 (0)