Connect AI agents to a hosted workbench

Goal: Plug Claude, Cursor, ChatGPT, or fai into a workbench's MCP endpoint and start calling its tools from your AI conversations.

---

Prerequisites

• A hosted workbench with MCPMode enabled — see Install a workbench from source.
• A Bearer JWT with the Workspace.Workbench.Host access right.
• The AI client of your choice installed locally.

---

Your workspace URL

Once a workbench is hosted, its MCP endpoint is:

<your-workspace-url>/oi-api/workbenches/{APISlug}/MCP

For example, a workbench with APISlug alerting on Open Industrial is at https://www.openindustrial.co/oi-api/workbenches/alerting/MCP.

---

Option 1: fai mcp install (recommended)

The fastest way to add a hosted workbench to any local AI agent is with the fai CLI. One command wires the workbench into Claude, Cursor, Copilot, and any other MCP-aware agent installed on your machine:

fai mcp install \
  <your-workspace-url>/oi-api/workbenches/alerting/MCP \
  --name alerting \
  --auth <your-jwt>

fai reads your local agent configs and adds the workbench as an MCP server named alerting. Restart your AI clients and the workbench's tools show up.

---

Option 2: Claude Desktop config

If you'd rather edit Claude Desktop's config file directly:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your workbench under mcpServers:

{
  "mcpServers": {
    "alerting": {
      "type": "streamable-http",
      "url": "<your-workspace-url>/oi-api/workbenches/alerting/MCP",
      "headers": {
        "Authorization": "Bearer <your-jwt>"
      }
    }
  }
}

Restart Claude Desktop. The workbench's tools appear in the hammer icon.

---

Option 3: Cursor config

Cursor's MCP server config lives in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "alerting": {
      "url": "<your-workspace-url>/oi-api/workbenches/alerting/MCP",
      "headers": {
        "Authorization": "Bearer <your-jwt>"
      }
    }
  }
}

Restart Cursor. The tools are available in Composer.

---

Option 4: Custom MCP client

Any client that speaks the MCP HTTP-Streamable transport can connect. The essentials:

• URL: <your-workspace-url>/oi-api/workbenches/{APISlug}/MCP
• Header: Authorization: Bearer <your-jwt>
• Transport: HTTP-Streamable (per the MCP spec)

The proxy validates the JWT and the Workspace.Workbench.Host right on every request, resolves the mode segment (/MCP) verbatim against the workbench's declared modes, and forwards to the workbench's container.

---

Tool namespacing

Every hosted workbench's tools are namespaced by its APISlug — {APISlug}.{toolName}. This prevents collisions when you host multiple workbenches in the same workspace.

For example, a workbench with APISlug alerting exposing a tool create_rule is callable as alerting.create_rule from any AI agent connected to it.

---

Coming soon: Azi auto-connect

Azi will automatically connect to every hosted workbench in your workspace that has MCPMode enabled and AziAccess left on (default), as discrete per-workbench connections — no manual install required.

---

Troubleshooting

Issue	Solution
Client can't connect	Check the URL — the mode segment (/MCP) is case-sensitive and matches the workbench's declared mode key verbatim.
401 Unauthorized	JWT expired or missing the Workspace.Workbench.Host right. Refresh the token and confirm your access rights.
Tools don't appear after config change	Fully quit and reopen your AI client — MCP servers are read at startup.
Tool call hangs on first invocation	Container may be cold-starting. First call takes 5–15s; subsequent calls are fast. Set minReplicas: 1 on the workbench Hosting tab for always-on.
Multiple workbenches, wrong tool called	Confirm tool names — each workbench namespaces its tools by APISlug (alerting.create_rule vs pricing.create_rule).

---

Next steps

If you want to...	Go to...
Install another workbench	Install a workbench from source →
Understand the mode model	Workbenches overview →
Manage API keys	Secrets →
Connect to the workspace-level MCP server	MCP Integration →