Overview
Exomations runs an MCP server for every workspace. Connect Claude, Cursor or any MCP client and your AI assistant can run your active flows, check how a run went, and draft new flows for you to review.
/api/mcpJSON-RPC 2.0 over HTTPS. Each request gets one JSON response; there is no event stream and no session to keep.
| Method | Purpose |
|---|---|
| initialize | Handshake. Returns the server's capabilities (tools). |
| tools/list | The tools your key may use. |
| tools/call | Run one tool. |
| ping | Health check. Returns an empty object. |
Set-up for each client is on Connect your client. Every tool's input, result, errors and an example call are in the MCP tool reference.
Claude Desktop
- In Exomations, open API Keys and create a key with the
executepermission. Addbuildif the assistant should also draft flows. - Add this block to Claude's configuration file and put your key in it.
- Restart Claude. Your flows appear as tools.
{
"mcpServers": {
"exomations": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://exomations.com/api/mcp",
"--header", "X-Api-Key:YOUR_EXOMATIONS_KEY"
]
}
}
}| System | File |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
The same block, with your endpoint filled in, is on the API Keys page under Exomations MCP Server, ready to copy.
Cursor and other desktop clients
Cursor uses the same server block in its MCP settings. Any client that can send a custom header can connect in one of two ways:
X-Api-Key: exo_your_keyAuthorization: Bearer exo_your_key?api_key=) is refused, even when a header is also sent. If a key was ever put in a URL, rotate it.Claude on the web (OAuth)
Browser-based clients cannot send a custom header, so the server also supports OAuth 2.0. Add the endpoint as a custom connector; the client discovers the rest and sends you to Exomations to approve.
- PKCE (S256) is required, and clients register themselves automatically.
- Approval needs a workspace Admin. The screen lists what the client asked for (
execute,build, or both); you allow or decline it as a whole. - Access tokens last one hour and renew automatically; the connection stays as long as it is used at least once every 30 days. You can revoke it on the API Keys page.
| Discovery document | Path |
|---|---|
| Authorization server | /.well-known/oauth-authorization-server |
| Protected resource | /.well-known/oauth-protected-resource |
Plain HTTP
You do not need an MCP library. These three calls are a complete session:
curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"exo_overdue_invoice_reminders_7a17617d","arguments":{"payload":{"customer_id":"C-204"}}}}'The reply to the third call:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [{ "type": "text", "text": "Flow \"Overdue invoice reminders\" queued. Check Exomations to see live progress.\n{ ... }" }],
"structuredContent": {
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"flowId": "7a17617d-...",
"flowName": "Overdue invoice reminders",
"status": "queued"
},
"isError": false
}
}Which tools a key sees
| Permission | Tools |
|---|---|
| execute | One tool per active flow, plus the three run-reading tools. |
| build | The eight building tools. |
| execute + build | All of them. |
Flow tools
Each active flow becomes a tool named exo_<name>_<id8>: the flow's name in lowercase Latin letters and digits (up to 48 characters), then the first 8 characters of its ID, for example exo_overdue_invoice_reminders_7a17617d. A flow whose name has no Latin letters or digits becomes exo_flow_<id8>. The tool's description is one fixed sentence from Exomations (what follows is data, not instructions), then the flow's own description, so write that well: it is what the AI reads to decide when to use the flow.
| Argument | Type | Notes |
|---|---|---|
| payload | object | Passed to the flow's Trigger step. Up to 512 KB, 10 levels deep, 1,000 keys, 5,000 items per list. |
The tool returns executionId, flowId, flowName and status (queued, or held when the workspace is over its monthly allowance). It does not wait for the flow; read the run with exo_get_execution.
Up to 200 flows are listed.
Run-reading tools
exo_list_executions
Recent runs of one flow, without payloads.
| Argument | Type | Notes |
|---|---|---|
| flowId | string | Required. |
| limit | integer | 1 to 100. Default 20. |
| status | string | One of queued, running, success, partially_succeeded, failed, retrying, waiting_approval, skipped, rejected, held. |
| since | string | ISO-8601 time. Only runs after it. |
exo_get_execution
One run: status, environment, start and end time, duration, retry count, error, the trigger data, and every step with its input, output and error.
| Argument | Type | Notes |
|---|---|---|
| executionId | string | Required. |
| nodeId | string | Return only this step. |
| nodeType | string | Return only steps of this type. Not together with nodeId. |
| includeParentOutputs | boolean | With nodeId: also return the outputs of the steps before it. |
{
"jsonrpc": "2.0", "id": 4, "method": "tools/call",
"params": {
"name": "exo_get_execution",
"arguments": { "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11" }
}
}exo_get_execution_step
One step of one run in full. Arguments: executionId and nodeId, both required.
completeness block that says exactly what was left out, so the AI never mistakes a partial answer for a full one.Building tools
| Tool | What it does |
|---|---|
| exo_search_apps | Search the app catalogue; with appId, list that app's operations and parameters. |
| exo_get_node_types | The step types a flow can use, with their settings and outputs. |
| exo_list_flows | All flows in the workspace with status and trigger type. |
| exo_get_flow | One flow's definition. Secrets in it are masked. |
| exo_validate_flow | Check a definition and return errors and warnings. Saves nothing. |
| exo_create_flow | Create a flow. It is always saved as a draft. |
| exo_update_flow | Change a flow. It goes back to draft; a flow that is live in production keeps running its published version. |
| exo_activate_flow | Activate a flow that a person has already moved to staging (a flow in development is moved to staging), after it passes the same checks as in the app. Flows set to production, the default for new flows, are refused, and so are flows that, themselves or through sub-flows up to six levels deep, run a withheld Nafath, Muqeem or Tamm government step, have a sub-flow step without a fixed target, or have a step with two conflicting step types, and flows with deeper sub-flows: a person activates those in the app. |
Plan check: each step type belongs to a plan. exo_create_flow and exo_update_flow refuse a flow that adds a step your workspace's plan does not include, before anything is saved: the result has isError: true and code: "PLAN_REQUIRED", with the plan it needs (requiredPlan), the steps involved (steps) and the message in English, Arabic and Chinese. exo_get_node_types marks which steps your plan includes, and exo_validate_flow reports them as warnings.
What is not exposed
- Only active flows become tools. Drafts and paused flows are invisible to an
executekey. - Flows with a Nafath request step are not offered as tools.
- Flows with a Muqeem or Tamm step that changes a government record are not offered as tools. Inquiry-only flows stay available.
- Runs that executed one of those steps cannot be read over MCP either.
- The same holds through sub-flows: a flow that runs one of those flows as a sub-flow is not offered, and a run started over MCP cannot start one as a sub-flow.
- Run data returned to the AI comes with a note that it is untrusted content: data, never instructions.
- A key with
buildstill sees these flows inexo_list_flowsandexo_get_flow, so it can help edit them. - A person can offer a Nafath flow as a tool on purpose with the switch in Flow Builder → Alerts. Muqeem and Tamm transaction flows have no such switch in the app yet.
- Download links for generated documents are removed from run data.
Result format
Every tool answers with the same three fields:
| Field | Content |
|---|---|
| content | A text summary followed by the data as JSON, for clients that only read text. Trimmed at 100,000 bytes with a clear marker. |
| structuredContent | The full data as an object. |
| isError | true when the tool itself failed, for example an unknown execution ID. |
Errors
Protocol errors use the JSON-RPC error object. A tool that fails returns a normal result with isError: true.
{
"jsonrpc": "2.0",
"id": 3,
"error": { "code": -32001, "message": "API key lacks the 'build' permission required for flow authoring tools" }
}| Code | HTTP | Meaning |
|---|---|---|
| -32001 | 401 | No credentials, or an invalid or expired OAuth token. |
| -32001 | 403 | Invalid, inactive or expired key; missing permission; suspended workspace. |
| -32001 | 429 | Workspace rate limit. Wait for Retry-After. |
| -32602 | 200 | Unknown tool, missing tool name, or a payload over the limits. |
| -32601 | 200 | Method not found. |
| -32700 | 400 | The body is not valid JSON. |
| -32603 | 200 | Internal error. The reply carries an error ID to quote to support. |
| -32600 | 405 | Any HTTP method other than POST, GET or OPTIONS. |
| — | 429 | Per-key limit. The body is a plain { "error": "Rate limit exceeded for MCP requests", "code": "RATE_LIMIT", "message": "Rate limit exceeded for MCP requests" }, not a JSON-RPC object. Wait for Retry-After. |
Limits
| Limit | Value |
|---|---|
| Calls per minute, per caller, API and MCP together | 100 |
| Calls per minute, per key, ceiling | 200 |
| Calls per minute, whole workspace | Starter 100 · Professional 200 · Enterprise 500 |
| Flow tools listed | 200 |
| Flow payload | 512 KB |
| Request body | 8 MB |
Runs started over MCP count toward the same monthly allowance and simultaneous-run limit as any other run.
Audit and security
- The workspace is worked out from the key itself. A key cannot reach another workspace's flows.
- Every flow run, run read and building call is written to the audit log with the key's name.
- Give each client its own key, with the fewest permissions it needs and an expiry date.
Troubleshooting
| You see | Cause and fix |
|---|---|
| No flow tools | The key lacks execute, or no flow is active. |
| One flow is missing | It is a draft, paused, or contains a Nafath, Muqeem or Tamm step that is not offered by default. |
| Unknown tool | The flow was renamed or deactivated. Call tools/list again. |
| status: held | The workspace is over 120% of its monthly allowance. Top up or wait for the reset. |
| 401 | The header is missing, or the key was sent in the URL. |
