Reach a Workbench over MCP

Goal: Plug an AI client into a hosted workbench and call its tools from your conversations.

Every MCP endpoint of a hosted workbench is its own MCP server, at a stable address under your workspace. Any client that speaks MCP connects the same way. This page is for the workbench you host; the server that reads your warm queries and takes proposals is the OpenX MCP server, at a different address.

Before you start

• A hosted workbench, see Host Your Own Workbench, with a port marked MCP capable, see Serve MCP from a Workbench.
• A key from APIs -> API Keys, while the workspace's API identity (set in the API Manager) is Team (the default) or Hybrid. It needs no particular access right. Under App Identity, team keys are turned away and a caller needs an access token from an App Identity you trust.
• The AI client you want to use.

The address

https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/<apiSlug>/<key><path>

<workspace id> is the ID shown in Workspace -> Settings. <apiSlug> is the workbench's APISlug, set in its Hosting tab; the slug in the examples (alerting) is a stand-in for your own. <key> is the mode's key and is case-sensitive; the examples use a mode keyed MCP with MCP at its root, so they leave <path> off. The API Manager's Workspace MCP group lists every endpoint with its full address.

Option 1: fai mcp install

With fAI installed, one command adds the workbench to every MCP-aware coding agent on your machine:

fai mcp install https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/alerting/MCP --name alerting --global --auth "<YOUR_TOKEN>"

fAI reads your local agent configs and adds the workbench as an MCP server named alerting. Restart your AI clients and its tools appear.

Option 2: Claude Desktop

Claude Desktop's config file takes local stdio servers only, so reach the workbench through the mcp-remote bridge. Edit claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\) and add under mcpServers:

{
  "mcpServers": {
    "alerting": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/alerting/MCP",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Restart Claude Desktop. A plain "url" with "headers" entry, and "type": "streamable-http", are both rejected in this file; the bridge is what connects. The key rides in env and not in args because Claude Desktop on Windows does not escape spaces inside args.

Option 3: Cursor

Cursor reads ~/.cursor/mcp.json:

{
  "mcpServers": {
    "alerting": {
      "url": "https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/alerting/MCP",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Restart Cursor and the tools are available.

Option 4: any MCP client

Any client that speaks the Streamable HTTP transport can connect. It needs:

• the address above;
• the header Authorization: Bearer <YOUR_TOKEN>;
• the Streamable HTTP transport. This is not SSE, and a client set to the old SSE transport does not connect at all. Streamable HTTP frames some responses as text/event-stream, which is easy to mistake for SSE; seeing it is not a reason to change the client.

OpenX checks the caller against the workspace's API identity on every request, matches the mode segment (MCP) exactly against the modes the workbench has turned on, and forwards to the workbench's container.

What the tools are called

Each workbench is its own server, and its tools are named by the workbench's author. A tool method is published as the tool's name and the method's name, in lowercase, joined by a hyphen: a tool called Hello with a method Greet is hello-greet. OpenX adds nothing to the name. Names do not carry the APISlug; if you host three workbenches, a client shows three servers, each under the name you gave it with --name, each with its own tools.

If something's off

Issue	Do
The client cannot connect	Check the address. The MCP segment is case-sensitive and must be a mode the workbench has turned on
401	The key has expired, or the API identity is App Identity, which turns team keys away. Make a new key, or use an App Identity token
Tools do not appear	Quit and reopen the client fully. Clients read their MCP servers at startup
The first call is slow	A mode can scale down to no containers when idle (the default). The first call starts one; later calls are quick. Set Min replicas to 1 in the Hosting tab to keep one running. A mode that is not deployed yet answers 503 "is not deployed yet"
A tool is missing	Check the workbench declares it. Run it locally with fai run <Entry> --mode MCP and list the tools

Next steps

• Call it from code or a page -> Reach a Hosted Workbench
• Build another -> Host Your Own Workbench
• Keys and expiry -> Auth & Tokens