Serve MCP from a Workbench
Goal: Tell OpenX which of your workbench's ports speak MCP, so each one gets its own address, its own tab in the API Manager and, if you allow it, a place in Azi's tools.
A mode is a name
A workbench declares its modes under keys of your choosing: MCP, API and Web are names like any other,
and Site or Ops work the same way. The key is the mode's name, the segment in its address and the value
fai run takes with --mode. OpenX reads nothing else into it, and a key is case-sensitive.
A workbench can be several things at once: an API, a web interface, an MCP server, a background job, or any
mix. So OpenX never guesses what a mode serves from its name. Your package declares its ports (.Ports()),
and you say which of them speak MCP.
Mark a port MCP capable
- Select the workbench on the canvas and open its Modes tab.
- Press Load workbench modes. The inspector reads the modes and ports your package declares. Until it has, each port says "Load workbench modes to see each port's MCP settings."
- Under the port that answers MCP, turn on MCP capable. With no paths listed, the port's root,
/, is the MCP endpoint. - Save.
An MCP endpoint needs an HTTP port. On a TCP port the switch stays off and says "MCP needs an HTTP port. This port is TCP."
MCP on a sub-path
When MCP lives below the root, for example at /mcp, type the path into Add an MCP path and add it. The
paths you list replace the root, and the port then says "root removed: re-add / if the root also speaks
MCP". Each path is its own endpoint. Remove takes one away.
| Rule | What the save says |
|---|---|
| The path's form | "An MCP path must start with /, have no trailing / (except /), no // and no . or .. segments, no ? or #, and be at most 256 characters." |
| At most 10 per port | "A port takes at most 10 MCP paths." |
| At least one path | "Turn MCP off instead of removing every path." |
| An HTTP port | "MCP needs an HTTP port." |
| A port the package declares | "MCP is set on a port this package doesn't declare. Load workbench modes and pick a declared port." |
A port your package no longer declares keeps its old setting, marked "port no longer declared", until you remove it. It serves nothing.
The address
A public endpoint on the mode's primary port answers at:
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.<key>is the mode's key, exactly as written.<path>is the MCP path. Leave it off for the root.
For example, a mode Ops with MCP at /mcp answers at
https://openx.fathym.com/ox-api/w/<workspace id>/workbenches/alerting/Ops/mcp.
Inside the environment only. An endpoint on a port other than the mode's primary one, or on a workbench set
to no public access, has no public address. Other workbenches and machines in the same environment reach it
at http://<app name>:<port><path>, and the API Manager shows that address and a fai mcp install
command to run from a machine there.
Let Azi use it
Each MCP path has its own switch, Azi may use this endpoint:
- Off (the default): Azi never calls these tools.
- On: Azi may call them in this workspace's chats.
The switch is per path, so one workbench can offer Azi one endpoint and keep another for your own clients.
Find it in the API Manager
Open APIs -> API Manager. Below the platform tabs are two groups:
- Workbenches: a tab per workbench, with a card per mode you turned on. A card shows the mode's health,
Open for its page (
.../<key>/), the Base URL (.../<key>) to copy, its routes when it publishes an OpenAPI catalog, and how many MCP endpoints it serves ("MCP: 2 endpoints, see Workspace MCP"). A mode that is not deployed yet says "Not deployed yet: Deploy to get an address." - Workspace MCP, at the bottom: a tab per MCP endpoint, named
<workbench> · <key><path>. Each has the Server URL to copy, the name a client gives it (ox-<4 characters of your workspace>-<apiSlug>-<key>, with the path at the end for a sub-path), set-ups for each client, and the rights the mode asks for.
When the root of a mode's primary port is MCP, the mode has no card under Workbenches, because its address is that MCP endpoint, listed under Workspace MCP. A workbench with no card has no tab there.
SIGN-IN IS STILL LANDING
The Workspace MCP tab's set-ups carry no key, because signing in to each workbench endpoint is still landing. Until it does, connect with a key the way Reach a Workbench over MCP shows. Try it on these tabs can't sign in yet, and says so.
Next steps
- Connect a client -> Reach a Workbench over MCP
- Everything the API Manager shows -> API Manager
- Host the workbench -> Host Your Own Workbench