MCP Server — Controller
Each Aida Controller can run an on-appliance MCP server so Platform agents and external MCP clients (Hermes, Cursor, Claude Code, and similar) can configure, commission, operate, and monitor that controller through curated tools — not by scraping OpenAPI.
Enable MCP
- Sign in to the controller (LAN or Platform Remote).
- Open Modules → MCP (or System MCP settings).
- Enable the MCP module and review options (mutating tools, transports).
- Confirm health shows MCP reachable when the module is on.
When the module is disabled, /mcp returns 404.
:::warning Do not expose MCP on the public internet
Reach the controller MCP on the LAN, or through Platform remote access / approved tunnels. Do not publish /mcp as an open WAN endpoint.
:::
Endpoints (on the controller)
| Transport | Path | Use |
|---|---|---|
| Interim REST (tools / resources / prompts) | /mcp/… | Scripts and custom HTTP agents |
| Streamable HTTP (native MCP) | /mcp/http | Hermes, Cursor, Claude Code, MCP SDKs |
| Agent token mint / exchange | /mcp/agent-tokens, /mcp/agent-tokens/exchange | Short-lived Bearer JWTs |
Example Streamable HTTP URL on the LAN:
http://{controller-unicast-ip}/mcp/http
Through Platform remote access, use the remote gateway URL for that controller with the headers your remote session requires (controller id + authorization). Gateway ACLs must allow /mcp (and subpaths).
Authentication
Controller MCP uses Bearer JWTs (user or short-lived mcp_agent tokens) — not the static X-API-Key keys from Settings → API Keys.
| How you get a token | Typical flow |
|---|---|
| LAN / lab | Log in → optional POST /mcp/agent-tokens → Authorization: Bearer … |
| OAuth (browser) | MCP client auth: oauth → operator consent in the controller SPA → agent JWT |
| Platform-mediated | Platform exchange assertion → POST /mcp/agent-tokens/exchange → agent JWT |
Tokens are short-lived (typically minutes to about an hour). Re-mint or refresh before expiry. RBAC capabilities such as mcp.connect, mcp.read, mcp.write, and mcp.admin gate tools.
Static API keys for REST remain documented under API Keys — Controller.
What MCP is for
| Goal | Approach |
|---|---|
| Configure / commission / operate / monitor | Curated MCP tools mapped to controller services |
| Durable automation | Prefer installing schedules, modules, and Automation playbooks; MCP installs and supervises |
| Multi-agent safety | App identity, leases, and audit (source=mcp) |
MCP does not replace the controller UI for human operators and does not talk to field devices by bypassing the controller.
Example client config (Streamable HTTP)
mcp_servers:
aida_controller:
url: "http://{controller-unicast-ip}/mcp/http"
headers:
Authorization: "Bearer <mcp_agent_or_user_jwt>"
Prefer OAuth where the client supports it so operators consent with their existing controller login.
Licensing
MCP and related AI surfaces typically require Pro (or an active Trial). See Licensing.