MCP Server (AI Agent Integration)
The Nexomatic MCP server exposes your automation workflows as typed tools that AI agents (Claude Desktop, Claude Code, and any MCP-compatible agent) can call directly. Every flow with an MCP source becomes a tool — no custom code required.
Prerequisites
Section titled “Prerequisites”Before starting, you need a source node for the MCP source to run on:
- Open the Nexomatic UI and create a source from the MCP preset (on the Sources screen, or in a flow’s WHEN block). The source carries two auth tiers as config params:
- API key (the common tier): create a secret on the Secrets page and pick it for
mcp_api_key— MCP clients present it asAuthorization: Bearer <key>. - OAuth / Entra ID (optional): point
oauth_issuerat your Entra tenant’s v2 endpoint (or another Authorization Server), setoauth_audienceandoauth_client_idfrom the app registration, pick the app registration’s secret foroauth_client_secret, and keepoauth_scopesasmcp:read mcp:write. Leave the issuer empty to keep the OAuth tier off.
- API key (the common tier): create a secret on the Secrets page and pick it for
- The MCP server runs on a source node: use that node row’s Client ID and Client Secret from the Nodes screen (the secret shows once at node creation; regenerate from the row’s menu if lost)
- Note the Tenant UUID from tenant settings
Connecting an agent
Section titled “Connecting an agent”The MCP server runs on your source node and serves streamable HTTP (default port 8002, the source’s mcp_port param). Agents connect to the node’s endpoint instead of spawning a local process:
claude mcp add nexomatic --transport http https://<source-node-host>:8002/mcp/<tenant-uuid>Authentication follows the source’s config: with the API-key tier (the default), the client presents the key — add it to the agent’s MCP config as a bearer header (or use a client that prompts for it); with the OAuth tier configured, the client completes the authorization-code flow against the issuer (e.g. your Entra ID). A source with neither tier configured serves with local trust — set the API key before exposing the endpoint.
Verifying the Connection
Section titled “Verifying the Connection”After connecting, open a Claude conversation. Ask:
“What Nexomatic tools do you have available?”
Claude should list one tool per flow with an MCP source in your tenant (e.g., send_email, run_report), plus the static tools: list_events, get_event, list_event_types, list_schedules, create_schedule, update_schedule, delete_schedule, get_current_tenant.
If the tool list is empty, check that your tenant has flows with MCP sources configured in the Nexomatic UI.
Using the Tools
Section titled “Using the Tools”Triggering workflows
Section titled “Triggering workflows”Tool names mirror your flow names (lowercased, spaces replaced with underscores). If you have a flow “Send Email” with parameters to, subject, body, you can trigger it with:
“Send an email to alice@example.com with subject ‘Report ready’ and body ‘Your weekly report is attached.’”
Claude calls send_email(to="alice@example.com", subject="Report ready", body="...") directly.
Note: SECRET-type parameters are not in tool signatures — they are pre-configured in the system and resolved automatically at execution time.
Monitoring execution
Section titled “Monitoring execution”After triggering a workflow, ask Claude to check progress:
“What’s the status of that event?”
Claude calls get_event(event_id=...) which reads from the local cache kept live by the Hub. If the workflow triggered a chain (a success or failure follow-up), the result includes chained_event_id so Claude can follow the full chain.
Querying recent events
Section titled “Querying recent events”“Show me any failed events from today.”
Claude calls list_events(state="ERROR", limit=20).
Managing schedules
Section titled “Managing schedules”“Schedule the daily report to run every morning at 8am.”
Claude calls create_schedule(name="Daily report", cron="0 8 * * *", event_type_slug="run_report") — this adds a schedule row bound to that flow. Scheduling is the same mechanism the UI exposes as the Every day at… preset (the cron on the source, plus per-flow trigger rows in the WHEN block) — the MCP tools manage the same schedules programmatically.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Empty tool list | No flows with MCP sources in the tenant | Add an MCP source to a flow in the Nexomatic UI |
| Tool name collision warning in logs | Two flows with the same slug | Rename one flow or accept the UUID-suffixed tool name |
| Stale event state after reconnect | Disconnected during execution | The server resyncs on reconnect; wait a moment and retry get_event |