Matching widget to MCP tool

When an MCP (Model Context Protocol) tool is invoked, OpenBB Workspace can automatically detect if there's a matching widget configured and provide a matching citation. This is achieved through configuration in your widgets.json file.

How It Works

OpenBB Workspace checks if a widget has been configured with matching MCP tool metadata. When a match is found:

1. The system shows a notification that a matching widget was found
2. A citation is automatically generated and attached to the MCP tool response
3. The citation includes widget details like name, description, and input parameters

Configuration

important

mcp_server and tool_id provided should match 1:1 the ones that are connected to OpenBB Copilot.

To enable widget matching for MCP tools, add an mcp_tool property, like:

"mcp_tool": {
  "mcp_server": "server_name",
  "tool_id": "tool_name"
}

The widget configuration in widgets.json should be like:

{
  "widgetId": "your_widget_id",
  "name": "Your Widget Name",
  "description": "Widget description",
  ...
  "mcp_tool": {
    "mcp_server": "server_name",
    "tool_id": "tool_name"
  }
}

Example

We will utilize this repository example as a way to demonstrate the flow.

1. Connect MCP Server

First you want to connect the MCP Server to identify the server name and tool that you will need to reference in your widgets.json configuration.

In the case above, note that the name of MCP Server is "Financial Data" - this will be the value you need for the mcp_server field in your widgets.json.

Similarly, the MCP tool is "get_company_revenue_data" - this will be the value you need for the tool_id field in your widgets.json.

2. Configure OpenBB widget with matching MCP

The important is for the widget configuration to include mcp_tool with the EXACT same names as the ones from your MCP Server:

Notice how the mcp_server value "Financial Data" and tool_id value "get_company_revenue_data" match exactly with the MCP server configuration from step 1.

The name and URL of the backend can be ANYTHING.

3. Matching widget citation

This is when the magic happens. If the user has that MCP tool enabled, and asks something like:

"Utilize financial data MCP tool and get company revenue data for AAPL"

Then when the MCP tool is utilized, the user will see a toast like the following:

This indicates that a matching widget was found.

The user will be able to see that this is a matching widget, by the property of having a * at the end.

When hovering on top of that widget, the user will be able to add it to the dashboard to the same parameters as the ones that were utilized by the copilot.

The advantage now is that the user can interact with the parameters, charting and all other OpenBB widgets properties.