Publish API Modules as MCP Tools

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

This guide walks you through publishing an API module as a tool on the environment's Model Context Protocol (MCP) endpoint. Afterward, an AI agent outside Unqork can call the module. For what the MCP server is, how it works, and its limits, see MCP Server for API Modules.

Requirements

Before you begin, confirm the following:

• UnqorkAI: MCP is part of UnqorkAI and has no separate setting. With UnqorkAI off, the endpoint and the module's MCP Settings page do not exist.
• Administrator rights: Creating Express roles and API credentials requires Creator access with environment administrator rights.
• Workspace permissions: Publishing a module as a tool requires Update permission on the workspace. View permission is enough to open the MCP Settings page.
• An API module: Set Module Type to API, which runs the module server-side only by default. A module that browsers can also load still publishes, with a caution. Any field in the module can be an input or an output, so request and response panels are optional.
• A secrets manager: You store the credential's Client Secret there, for example AWS Secrets Manager or Parameter Store.

Connect an AI Agent to Your Environment's MCP Endpoint

In this section, you create an Express role for the agent and publish an API module as a tool on the endpoint. You then create an API credential that holds only that role, request a token, and connect a client. An environment administrator creates the role and the credential. A Creator publishes the module, and the Build Agent writes the tool's first setup. When you finish, the agent can list and call the tool.

Create the Agent's Express Role

Create one role for each agent, or for each group of agents with the same reach. A new role reaches nothing until a module grants it access.

To create the role:

1. Navigate to Administration > Environment Settings > Express Permissions > Express Role Administration.
2. Select Create Express Role and enter a Role Name, for example SupportAgent.
3. Set Select Default Permission to No Access. Any other default lets the agent run every module that does not name the role. MCP rejects such a role and names the setting to change.
4. Leave Full Submission Access off, and leave Designer Access off if it displays. Either one bypasses module permissions, so MCP rejects a role that has it.

Publish an API Module as a Tool

Publishing a tool takes the following tasks: grant the role access, set up the tool, check who can call it, and save.

Grant the Role Write Access

The agent's role has Default Permission No Access, so it reaches nothing until a module grants it access. Granting Write on the module is what lets the agent call the tool and send its inputs. The module's permissions table is available when Customize RBAC for This Module is ON, which is the default for new modules. See Module-Level Role-Based Access Control (RBAC) for how module permissions resolve.

To grant the role access to the module:

1. In the Explorer panel, select (ellipsis) next to the API module and select Settings.
2. Open the User Permissions page and confirm Customize RBAC for This Module is ON. Set it to ON if it is off.
3. In the permissions table, set the agent's role to Write.

Read-Only does not work. The module ignores an agent's inputs under Read-Only, and the tool does not list the role as a caller.

If you skip this task, the Build Agent can make the same changes while it sets up the tool. It asks you to confirm each change.

Set Up the Tool

The Build Agent writes the first setup of a tool. It proposes the tool's name, description, inputs, and outputs in wording an agent can read. You review and approve the result. For every setting on the MCP Settings page, see MCP Settings.

To set up the tool:

1. Open the MCP Settings page. The page opens with a How to set up an agent guide that repeats these steps and displays the environment's MCP endpoint and token request.

2. Select Set up with Build Agent, or copy the message the page provides and paste it into the Build Agent. The button is unavailable while the form has unsaved changes. Save or discard them first.

   

3. Answer the Build Agent's questions. It explains what the agent needs, reads the module's configuration, and proposes the tool. It asks one question at a time.

4. Review the confirmation card. It names the tool, its description, every field an agent can send and receive, and the roles that can call the tool. Select Allow to publish.

The Build Agent asks for confirmation every time it publishes a tool, switches one off, or changes a role's permissions. Every approval mode requires the confirmation, and Always allow is not offered.

After the first setup, you edit the tool directly on the MCP Settings page.

The Agents can call this module as a tool (MCP) switch publishes the tool or switches it off. Switching a tool off keeps its settings and its name, so switching it back on needs no new setup. For the settings you can edit, see Tool Settings.

Check Who Can Call the Tool

The Who can call it group on the MCP Settings page lists the Express roles that can call the tool. These roles have Write on the module, and their own Default Permission is No Access. The group displays only while the Agents can call this module as a tool (MCP) switch is ON. It sits below the endpoint address and above the Tool group.

To check who can call the tool:

1. Open the module's Settings dialog, as described in Grant the Role Write Access.
2. Open the MCP Settings page.
3. Confirm the Agents can call this module as a tool (MCP) switch is ON.
4. Find the Who can call it group. Each role that can call the tool displays as a badge.

The page displays an alert in each of the following cases:

• Customize RBAC is off, so no agent can call this tool: Turn on Customize RBAC for This Module on the User Permissions page.
• No role can call this tool yet: Set the agent's role to Write on the User Permissions page.
• This role can't call this tool: The page names each role MCP rejects and the setting to change. The causes are Read-Only on the module, Designer Access or Full Submission Access on the role, or a Default Permission other than No Access.

Save the Tool

The Build Agent saves the tool for you. When you select Allow on the confirmation card, it saves the tool with the module's settings, so the first setup needs no Save. The settings dialog closes when you hand off to the Build Agent. Reopen the module's settings and open MCP Settings to review the saved tool.

When you edit the tool afterward on the MCP Settings page, select Save in the module settings dialog. Whether the Build Agent or you save the tool, the platform checks it first. The following issues block the save:

• Customize RBAC for This Module is OFF, or Act as Super-User when server-side executing is ON.
• A field in the tool has no component with that property ID in the module, or a field the module requires is marked optional.
• An output field's component has Persistent turned off, so the module never returns its value.
• The tool has no valid name, no description, or a field without a type.
• A limit is higher than the environment limit.

The following issues display as warnings and do not block the save:

• The module calls other modules or third-party services.
• The module is not set to Server-side Execution Only, so browsers can also load it.
• The module is large.
• The module returns values the tool does not declare.
• A required field is left out of the tool.
• The tool declares no outputs.

In an application without versioning, a save takes effect on the next call. In a versioned application, publish the tool in a development environment, then promote it. See When Changes Take Effect for details.

Create the Agent's API Credential

An environment administrator creates the credential. The Build Agent cannot.

To create the credential:

1. Navigate to Administration > Environment Settings > Integration > API Access Management.
2. Select Create Express API Credential.
3. Enter a Name for the credential.
4. In Select Express Role(s), select only the agent's role. Do not map applications to other roles, because MCP rejects a credential with application role mapping.
5. Enter the Days to Expiration. The credential displays Expires Soon during its last 21 days and Expired afterward, so generate a new secret before then.
6. Select Create Credential and copy the Client ID and Client Secret directly into your secrets manager. Do not place them in code, in a configuration file under source control, in a chat message, or in a ticket.

MCP accepts only an Express API credential that uses the client credentials grant. A Creator's sign-in or a password-grant token is never accepted. See API Access Management for the full credential reference.

Get a Token

Request the token from the token endpoint on the environment's Express host. The Designer host rejects API credentials with 403 Designer Access Denied. See Endpoint for Each Environment for the host patterns.

To request a token, load the Client ID and Client Secret from your secrets manager into environment variables, then run the following request. The How to set up an agent guide on the MCP Settings page displays the same request, with the environment's address already entered.

curl -s -u "$UNQORK_CLIENT_ID:$UNQORK_CLIENT_SECRET" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode resource=https://{express-host}/api/1.0/mcp \
  https://{express-host}/api/1.0/oauth2/access_token

The response contains access_token, expires_in (3600), and token_type (Bearer). The token lasts 60 minutes and cannot be refreshed, so request a new one before it expires. See Authentication and Tokens for token behavior and how to handle tokens securely.

Connect a Client

An MCP client connects to the endpoint with the bearer token. The following clients work today:

• A client SDK: Use the Streamable HTTP transport of any MCP client SDK. Attach the bearer token through its custom fetch or header so the token can be renewed. The following example uses the official TypeScript SDK, pinned to version 1.32.2 (@modelcontextprotocol/sdk@1.32.2).
• Claude Code: Works with a pasted token. Request the token before you begin Claude Code, and again after an hour.
• Postman: Sends the same requests without an agent or code. See Test the Endpoint With Postman.

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(new URL(process.env.UNQORK_MCP_URL), {
  fetch: async (url, init) => {
    const headers = new Headers(init?.headers)
    headers.set('authorization', `Bearer ${await tokens.getToken()}`) // renewed before expiry
    return fetch(url, { ...init, headers })
  }
})
const client = new Client({ name: 'my-agent', version: '1.0.0' })
await client.connect(transport)
const { tools } = await client.listTools()

Replace tokens.getToken() with your own function, which returns a current token and requests a new one before the old one expires.

For Claude Code, add the endpoint to a project's .mcp.json file and read the token from an environment variable so the file never holds it:

{ "mcpServers": { "unqork": { "type": "http", "url": "https://{express-host}/api/1.0/mcp",
  "headers": { "Authorization": "Bearer ${UNQORK_MCP_TOKEN}" } } } }

A client that only offers an OAuth sign-in flow cannot connect yet, because the endpoint issues tokens for client credentials only.

Test the Endpoint With Postman

Use Postman to confirm that your credential, role, and tool work before you connect an agent. The setup takes two requests. In both, replace {express-host} with the Express host that the MCP Settings page displays.

Store the Client ID and Client Secret as secret-type variables in a Postman environment. Do not type them into a request, and do not share a collection or environment that holds a token.

To get a token:

1. Create a request with the method POST and the URL https://{express-host}/api/1.0/oauth2/access_token.

2. On the Authorization tab, set Auth Type to Basic Auth. Enter the Client ID as the Username and the Client Secret as the Password.

3. On the Body tab, select x-www-form-urlencoded and add the following keys:

   Key	Value
   grant_type	client_credentials
   resource	https://{express-host}/api/1.0/mcp

4. Select Send and copy the access_token value from the response. The token lasts 60 minutes. Without the resource key, the MCP endpoint rejects the token.

To list the tools your credential can call:

1. Create a request with the method POST and the URL https://{express-host}/api/1.0/mcp.

2. On the Authorization tab, set Auth Type to Bearer Token and paste the token.

3. On the Headers tab, add Content-Type with the value application/json and MCP-Protocol-Version with the value 2025-11-25.

4. On the Body tab, select raw, set the format to JSON, and enter the following request:

   { "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
   

5. Select Send. The result.tools array lists each tool and its inputSchema.

To call a tool, replace the body with the tool's name and the inputs from its inputSchema:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "get_order_status", "arguments": { "orderNumber": "ACME-1003" } }
}

The response contains the following:

• result.structuredContent: The tool's outputs.
• result.isError: A value of true means the module rejected the call. The message names the field and the rule it broke.
• HTTP 401 or 440: The token is missing, expired, or requested without resource.

The server keeps no sessions, so you do not send an initialize request first. Postman's own MCP request type also works. Select HTTP, enter https://{express-host}/api/1.0/mcp, and add the header Authorization: Bearer <token>. If a tool is missing from the list, confirm that the role has Write on the module and the tool is switched on.

Set Up the Agent in Another Environment

A tool promotes with its module, but roles and credentials stay in the environment that created them. To move a working agent setup to another environment:

1. Promote the module, or the application version, to the target environment.
2. Promote the agent's role: in the source environment, navigate to Administration > Environment Settings > Express Permissions > Express Role Administration, select Promote Roles, then select the agent's role and the target environment. A role with the same name in the target environment is overwritten. To create the role by hand instead, see Create the Agent's Express Role. Either way, confirm that the role has Default Permission No Access.
3. In the target environment, open the module's MCP Settings page and confirm that the role displays under Who can call it.
4. In the target environment, create an API credential that holds only that role, as described in Create the Agent's API Credential. Credentials are not promoted.
5. Request a token from the target environment's Express host, and connect the agent to that environment's endpoint.

See Promote Tools to Another Environment for what promotes and what does not.