MCP Server for API Modules

The MCP server is a Beta feature for environments with UnqorkAI. Test each published tool and verify its results before relying on it.

The MCP server lets AI agents that run outside Unqork call API modules as tools. Each environment has one Model Context Protocol (MCP) endpoint, and a Creator chooses which API modules to publish through it.

An agent signs in with an Express API credential, and the credential's Express role decides which tools the agent can see and call. Every call is rate-limited and logged. To publish a module as a tool and connect an agent, see Publish API Modules as MCP Tools.

Key Terms

Readers must understand the following terms to use the MCP articles.

How the MCP Server Works

A tool is an API module that a Creator has published to the environment's MCP endpoint. The tool's settings are stored on the module, so the tool versions and promotes with the module. Deleting the module removes only its tool.

Publishing a tool has two parts. The Build Agent writes the first setup. It reads the module and proposes the tool's name, description, inputs, and outputs in wording an agent can read. A Creator reviews and approves that setup, then edits the tool afterward on the MCP Settings page of the module's settings.

What Happens When an Agent Calls a Tool

The following steps describe one complete call, from sign-in to result:

1. The agent requests an access token from the environment's token endpoint, using its credential's Client ID and Client Secret. The request names the MCP endpoint, so the token works only there.
2. The agent sends the token with each request to the MCP endpoint. The server checks the request's origin, the credential's request allowance, and the credential itself. It rejects Creator accounts and roles that bypass module permissions.
3. The agent asks for its list of tools. The server returns only the tools whose modules grant the credential's role Write.
4. The agent calls a tool with arguments. The server rejects arguments that the tool does not declare or that have the wrong type.
5. The server runs the module and applies its validation rules. If the module's own rules fail, the agent receives the field and the rule it broke, so the agent can correct the call.
6. The server returns only the outputs that the tool declares. It also records the call in Service Logs and the audit trail.

Who Does What

The Build Agent handles the module side. An environment administrator keeps control of the agent's identity.

The Build Agent can read the environment's Express roles to suggest one. It cannot create a role, create or change a credential, or issue a token. When it tests a tool, it runs the module directly to check the module's logic. That run does not go through MCP, so it does not test the agent's credential or access.

How an Agent Gets Access

An agent signs in as an Express API credential, never as a person. The credential's Express role decides which tools the agent can call:

• The role must have Default Permission No Access. MCP rejects any other default, because the agent could otherwise run every module that does not name the role.
• The role must not have Designer Access or Full Submission Access. Either one bypasses module permissions.
• The role must have Write on the User Permissions page of each module the agent calls. Customize RBAC for This Module must be ON. Read-Only does not work, because the module ignores the agent's inputs.
• Every role on the credential must meet these rules, and the credential must have no application role mapping. Give each credential one role, so an agent's reach is clear.

A Creator's sign-in or a password-grant token is never accepted. The server checks these rules on every request, so a change to a role or a module applies on the agent's next call.

Endpoint for Each Environment

Each environment has one MCP endpoint, https://{express-host}/api/1.0/mcp. Agents always use the environment's Express host. The Designer host rejects API credentials with 403 Designer Access Denied.

The MCP Settings page displays the exact address for the environment.

How Clients Connect

• Transport: The endpoint uses Streamable HTTP over https://. It accepts POST only and keeps no sessions.
• Protocol revisions: The server supports revisions 2026-07-28, 2025-11-25, and 2025-06-18. A request that names another revision receives a 400 response that lists the supported revisions.
• Capabilities: The server provides tools only. It publishes no resources or prompts, and it does not notify a client when its tools change.

Current client SDKs connect without changes, including the official TypeScript SDK and Claude Code.

Tool Settings

Each tool has a name, a description, the inputs an agent sends, the outputs it receives, and optional call limits. A Creator sets them on the MCP Settings page, and the Build Agent proposes them during the first setup. See MCP Settings for every setting.

• Name and description: Agents read these to decide when to use the tool, so both state what the tool does. A tool name is unique in the environment. If two modules claim the same name, the first module keeps it, and the second is not served until it is renamed.
• Inputs: The information an agent sends when it calls the tool, like an order number. An agent can send only the inputs that the tool lists.
• Outputs: The information the tool returns to the agent, like the status of an order. The result converts a value to its declared type when it plainly fits, like the text "12" to the number 12. It leaves out a value that cannot be that type.
• Call limits: Optional limits on how often one agent can call the tool. A tool limit can only be lower than the environment limit.

Leaving an input out of a tool restricts only agents that connect through MCP. A direct API call to the module can still set that field, so enforce any value that must not change in the module's logic.

When Changes Take Effect

In an application without versioning, a save takes effect on the next call. In a versioned application, the tool is saved in a draft and goes live with that draft's release. Publish tools in a development environment, then promote them. Until the application is released, it serves no tools.

A later edit can break a published tool, for example by turning off Customize RBAC for This Module or removing an exposed field. Agents then cannot call the tool. The MCP Settings page displays Agents can't call this tool right now with the reasons.

An agent that is already connected does not learn that its tools changed. A client sees a new, edited, or switched-off tool only when it lists its tools again, and most clients list tools only when they connect. After a change, reconnect or restart the client.

Promote Tools to Another Environment

A tool promotes with its module. The tool's settings and the module's User Permissions are part of the module. They move when a Creator promotes the module or its application version, and the switch that publishes the tool moves with them. Each environment keeps its own roles and credentials. An agent needs its own setup in the target environment before it can call the promoted tool.

If the module's role does not exist in the target environment, the MCP Settings page displays No role can call this tool yet.

In a versioned application, a Creator publishes the tool in a development environment, releases the version, and promotes it. The target environment serves the tool from the application's active version, and it serves no tools until a version is released.

A tool name is unique in an environment. If a module in the target environment already uses the name, the promoted tool is not served until a Creator renames it.

Authentication and Tokens

An agent requests a token from the token endpoint on the environment's Express host, using its credential's Client ID and Client Secret. Store the Client Secret in a secrets manager, never in code or source control.

Token Behavior

• Bound to the endpoint: The request includes a resource value that must name the environment's MCP endpoint exactly. The MCP endpoint rejects a token requested without it, and every other API route rejects a token requested with it.
• Lifetime: Every token lasts 60 minutes, for every credential and environment. The lifetime cannot be changed.
• No refresh token: The client credentials grant does not issue one. An agent requests a new token about a minute before expiry, and again whenever a call is rejected because of its token.
• Expired tokens: An expired token receives 440 Login Timeout instead of 401. Treat both the same way by requesting a new token and retrying once.
• No scopes: A token reaches exactly what its role reaches, which is the tools whose modules grant that role Write.

The token endpoint rejects a request with 400 and an invalid_target message in the following cases:

• The request uses resource with a grant other than client_credentials.
• The resource value is not an absolute address, names a different environment, includes a query or fragment, or does not name the MCP endpoint.
• The environment does not have UnqorkAI.

A token does not confine the credential. The same credential can still call the role's modules through the regular API with an ordinary token. MCP adds the call limits and the per-call audit to the MCP route only. Set a value that must never be caller-controlled in the module's logic.

Handle Tokens Securely

• Keep the token in memory and send it only in the Authorization: Bearer header. Never place it in a URL.
• Do not log tokens, request bodies, or authorization headers.
• Load the Client Secret from the secrets manager when the agent begins, and never type it on a command line.
• Connect only over https://.

Revoke an Agent's Access

An individual token cannot be revoked, and Express credentials have no Revoke action. Use the following controls instead:

Limits and Issues

Call Limits

Every message an agent sends to the endpoint counts as a request. The count includes the connection handshake (two messages), each list of tools, each tool call, and each ping. A request that the endpoint rejects after the request-limit check also counts, like a refused credential or an unknown tool. A request rejected before the check does not count. Examples are a request with an Origin header, a method other than POST, and a body that is not a JSON-RPC request. Getting a token does not count.

The allowance belongs to the API credential. Every copy of an agent that shares one credential shares one allowance, across every conversation and end-user it serves. Use separate credentials for separate deployments.

The minute is a fixed window. It begins with the credential's first request and resets 60 seconds later. Retrying before the reset returns another 429 and does not move the reset. The wait time displays in the message only, and the response has no Retry-After header.

Listing tools and the handshake do not use one of the two call slots. A call that takes a long time holds its slot until the module finishes. Each server instance counts its own slots, so an environment that runs several instances can allow more calls in total. Models often request several tools in one turn, so queue calls in the client two at a time.

The environment limits are the same for every agent and are not settings in the platform. A per-tool limit is the part that a Creator controls.

Responses an Agent Can Receive

The server answers a request that fails a check with an HTTP status and a JSON-RPC error. It answers a tool call that reaches the module with a result, even when the call fails.

HTTP Responses

Credential Refusals

A 403 response from the endpoint names the first rule that the credential fails. Each message includes the setting to change.

Tool Results

A tool result has isError: true when the module ran or was blocked. The message in the result tells the agent what to do next.

Validation

Every MCP call runs the module with validation on, and validation cannot be switched off. The rules are each component's own settings, like Required, a minimum or maximum length, or a pattern. They run after the module's logic, on the values it leaves. An empty value, a value of only spaces, or null counts as missing.

The engine does not validate a field that uses the Hidden component or is hidden on the form. For those fields, only the tool's own checks hold: the field's type and whether the tool marks it required. A minimum length or a pattern on such a field is not enforced. Use a visible component for a rule that must be enforced, or check the value in the module's logic.

When the module's own rules fail, the agent receives a tool result that names the field and the rule it broke. For example, an empty lastName field that is required returns "The module rejected these values: data.lastName Last Name is required. Correct them and try again."

Logging and Audit

Service Logs hold an entry for each tool call and each request for the tool list that passes the request limit. The audit trail records every tool call except one that the request limit stops. Neither location stores the tool's argument values or results, except for the module's own Remote Execute entry.

Each response carries the entry's identifier in the x-service-log-id header. Keep it in the agent's own logs to find a call later. Entries follow the usual workspace filter for logs. Entries with no module, like tool lists and calls rejected before a tool resolved, are visible only to people with environment-wide access. Retention is the same as for all Service Logs.

The Remote Execute entry holds request and response bodies as the environment's Server Side Execution Request/Response Body Log setting directs. The setting captures no bodies, the bodies of failed calls only (the default), or all bodies. It also follows the module's Capture Only Certain Fields in SSE Logs setting. See Module Settings for the setting. Agents often get a call wrong and retry, so expect more of these entries than a hand-written API client produces.

If a tool takes sensitive values, review the Server Side Execution Request/Response Body Log setting and the module's Capture Only Certain Fields in SSE Logs setting. Confirm that what is stored meets your organization's data-handling requirements.

In the audit trail, each tool call is recorded as an execute-module-as-agent event, including rejected calls, but not a call that the request limit stops. The event holds the credential, tool, module, and outcome, and never argument values or results. Publishing, changing, or switching off a tool writes the module's normal settings-save audit event.