---
title: "Publish API Modules as MCP Tools"
slug: "publish-api-modules-as-mcp-tools"
tags: ["guides", "api", "rbac", "unqorkai"]
status: "new"
updated: 2026-11-13T17:07:16Z
published: 2026-11-13T17:07:16Z
canonical: "docs.unqork.io/publish-api-modules-as-mcp-tools"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish API Modules as MCP Tools

> [!WARNING]
> 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](/unqorkai/docs/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 ![Landmark](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_e1fc877575ae47ab951373bebedef047.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **Administration** > ![Settings](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_11c03f9d0feb4fd9b3cf304524150614.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **Environment Settings** > ![ShieldCheck](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_ed4c7f4f17d148bdac065b2fb12b5dba.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **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)](/unqorkai/docs/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 ![EllipsisVertical](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_72e4311406484303aa4dd5030bd5b8ed.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) (**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**.

> [!WARNING]
> **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](/unqorkai/docs/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.

![[docs-interactive-image:{"surface":"module-settings/mcp-build-agent-setup","anchors":{"Set up with Build Agent":"set-up-the-tool","Message to paste":"set-up-the-tool"}}] The Set up this tool with the Build Agent section of MCP Settings, with the Set up with Build Agent button and the message to paste into the Build Agent](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_fced157692d74ec2a3b97a476119ea12.png?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D)
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.

> [!TIP]
> 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](/unqorkai/docs/mcp-server-for-api-modules#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](/unqorkai/docs/publish-api-modules-as-mcp-tools#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](/unqorkai/docs/mcp-server-for-api-modules#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 ![Landmark](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_e1fc877575ae47ab951373bebedef047.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **Administration** > ![Settings](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_11c03f9d0feb4fd9b3cf304524150614.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **Environment Settings** > ![Blend](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170715_0bba441bc4f944568dba0d07cfac168e.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **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](/unqorkai/docs/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](/unqorkai/docs/mcp-server-for-api-modules#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.

```bash
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](/unqorkai/docs/mcp-server-for-api-modules#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](/unqorkai/docs/publish-api-modules-as-mcp-tools#test-the-endpoint-with-postman).

```js
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:

```json
{ "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:

```json
{ "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`:

```json
{
  "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 ![Landmark](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_e1fc877575ae47ab951373bebedef047.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **Administration** > ![Settings](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_11c03f9d0feb4fd9b3cf304524150614.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **Environment Settings** > ![ShieldCheck](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261113_170714_ed4c7f4f17d148bdac065b2fb12b5dba.svg?sv=2026-02-06&spr=https&st=2026-11-14T00%3A06%3A42Z&se=2026-11-14T01%3A06%3A42Z&sr=c&sp=r&sig=8%2FMXX%2BcpbXNjCXH0WelaIBcaFoSGmmOcvk2Twk%2B8SB0%3D) **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](/unqorkai/docs/publish-api-modules-as-mcp-tools#create-the-agents-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](/unqorkai/docs/publish-api-modules-as-mcp-tools#create-the-agents-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](/unqorkai/docs/mcp-server-for-api-modules#promote-tools-to-another-environment) for what promotes and what does not.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-11-12 | Added a See Also link to MCP in Unqork. |
| 2026-11-05 | Initial draft for 9.2. |

A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource.

The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

Authentication secrets are a value of confidential information. For example, a password, security token, or cryptographic key, that is used to verify a user's identity during the authentication process to grant access to a system or application.

The client secret is a secret known only to the application and the authorization server. The client secret acts as the applications password to the server.

RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network.

A JavaScript property is a member of an object that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties.

A definition

Authentication secrets are a value of confidential information. For example, a password, security token, or cryptographic key, that is used to verify a user's identity during the authentication process to grant access to a system or application.

The client_id is a public identifier for apps

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

Fetching is the process of retrieving data from a database, making it available to the application and the end-user.

OAuth, or Open Authorization, is an authorization protocol that lets users grant third-party access to their information without sharing their passwords. OAuth is an industry standard that's used by many companies, including Google, Amazon, and Microsoft.

The HTTP POST method is used to send data to a server to create or update a resource, typically including the data in the body of the request.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

A bearer token is an HTTP authentication scheme that allows clients to generate a cryptic string used to authorize access to server resources.

JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.

An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.