Skip to content

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.

Before starting, you need a source node for the MCP source to run on:

  1. 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 as Authorization: Bearer <key>.
    • OAuth / Entra ID (optional): point oauth_issuer at your Entra tenant’s v2 endpoint (or another Authorization Server), set oauth_audience and oauth_client_id from the app registration, pick the app registration’s secret for oauth_client_secret, and keep oauth_scopes as mcp:read mcp:write. Leave the issuer empty to keep the OAuth tier off.
  2. 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)
  3. Note the Tenant UUID from tenant settings

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:

Terminal window
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.

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.

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.

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.

“Show me any failed events from today.”

Claude calls list_events(state="ERROR", limit=20).

“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.

SymptomLikely causeFix
Empty tool listNo flows with MCP sources in the tenantAdd an MCP source to a flow in the Nexomatic UI
Tool name collision warning in logsTwo flows with the same slugRename one flow or accept the UUID-suffixed tool name
Stale event state after reconnectDisconnected during executionThe server resyncs on reconnect; wait a moment and retry get_event