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. Each event type you configure becomes a tool — no custom code required.

Prerequisites

Before starting, you need a registered MCP source in Nexomatic:

1. Open the Nexomatic UI and navigate to Sources
2. Create a new source of type SOURCE:MCP
3. Note the Client ID and Client Secret — you’ll need these to configure the server
4. Note your Tenant UUID from tenant settings

You also need to know your Hub’s hostname and gRPC port (default: 50051).

Installation

Download the binary for your platform from the latest release in your Nexomatic repository:

Platform	File
macOS (Apple Silicon)	nexomatic-mcp-macos-arm64
macOS (Intel)	nexomatic-mcp-macos-x86_64
Linux x86_64	nexomatic-mcp-linux-x86_64
Windows x86_64	nexomatic-mcp-windows-x86_64.exe

No Python or other dependencies required — the binary is self-contained.

macOS / Linux: make the file executable after downloading:

chmod +x nexomatic-mcp-macos-arm64
# optionally move to somewhere on your PATH
mv nexomatic-mcp-macos-arm64 /usr/local/bin/nexomatic-mcp

macOS Gatekeeper: the first time you run it, right-click the file in Finder → Open, then confirm. After that it runs normally from the terminal and from Claude.

Claude Desktop Setup

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

{
  "mcpServers": {
    "nexomatic": {
      "command": "/usr/local/bin/nexomatic-mcp",
      "env": {
        "HUB_HOST": "your-hub-hostname",
        "HUB_PORT": "50051",
        "CLIENT_ID": "your-source-client-id",
        "CLIENT_SECRET": "your-source-client-secret",
        "NEXOMATIC_TENANT_UUID": "your-tenant-uuid"
      }
    }
  }
}

Replace /usr/local/bin/nexomatic-mcp with the full path to wherever you placed the binary. On Windows use the .exe path.

Restart Claude Desktop after saving. The MCP server starts automatically when Claude launches.

Claude Code Setup

claude mcp add nexomatic /usr/local/bin/nexomatic-mcp \
  --env HUB_HOST=your-hub-hostname \
  --env HUB_PORT=50051 \
  --env CLIENT_ID=your-source-client-id \
  --env CLIENT_SECRET=your-source-client-secret \
  --env NEXOMATIC_TENANT_UUID=your-tenant-uuid

Replace /usr/local/bin/nexomatic-mcp with the full path to the downloaded binary.

Verifying the Connection

After connecting, open a Claude conversation. Ask:

“What Nexomatic tools do you have available?”

Claude should list one tool per event type configured 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 event types configured in the Nexomatic UI.

Using the Tools

Triggering workflows

Tool names mirror your event type names (lowercased, spaces replaced with underscores). If you have an event type “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

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 (success_next routing), the result includes chained_event_id so Claude can follow the full chain.

Querying recent events

“Show me any failed events from today.”

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

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").

Troubleshooting

Symptom	Likely cause	Fix
Server exits immediately on start	Auth failure	Check CLIENT_ID, CLIENT_SECRET, and that the source exists in the UI
HUB_HOST unreachable	Wrong hostname or port	Verify HUB_HOST and HUB_PORT; check firewall
Empty tool list	No event types in tenant	Add event types in the Nexomatic UI
Tool name collision warning in logs	Two event types with the same slug	Rename one event type 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
macOS “cannot be opened” warning	Gatekeeper quarantine	Right-click → Open → confirm, or run xattr -d com.apple.quarantine nexomatic-mcp