> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/mcp-setup.md).

# Create MCP Tools

This guide walks you through creating a new MCP tool on the platform.

## What Is MCP? <a href="#what-is-mcp" id="what-is-mcp"></a>

MCP (Model Context Protocol) is a standard protocol that connects AI to external tools. An Agent connects to a remote MCP server through a URL to use the tools that the service provides.

### **MCP Solution** <a href="#mcp-solution" id="mcp-solution"></a>

Develop an MCP server once, and any AI platform that supports MCP can use it. For details on how the protocol works, the transports MaiAgent supports, and its limitations, see [MCP (Model Context Protocol)](https://docs.maiagent.ai/tech/mcp/mcp-model-context-protocol) in the technical manual.

## Quickly Create an MCP Tool <a href="#quick-create-mcp-tool" id="quick-create-mcp-tool"></a>

### 1. Open Tool Management <a href="#step-1-enter-tool-management" id="step-1-enter-tool-management"></a>

First, go to <mark style="color:blue;">AI Features</mark> → <mark style="color:blue;">Tools</mark> in the left menu. On the tool list page, click the <mark style="color:blue;">Add Tool</mark> button in the upper right.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-804dd5ac3ff8177e6576f5a48ecf21d57dc3ee79%2Fmcp-tools-list.png?alt=media" alt="Tool list page with the tool list and Manage Connectors on the left, and the Add Tool button in the upper right"><figcaption><p>Click “Add Tool” to get started</p></figcaption></figure>

### 2. Select the Tool Type <a href="#step-2-select-tool-type" id="step-2-select-tool-type"></a>

Select <mark style="color:blue;">MCP</mark> as the tool type.

### 3. Set the Display Name <a href="#step-3-set-display-name" id="step-3-set-display-name"></a>

Give the tool a clear display name. In this example, use <mark style="color:blue;">Composio mcp for google calendar</mark>.

* **Purpose**: This name appears in the platform interface for all users to see.
* **Recommendation**: Choose a name that clearly describes the tool's main function so users can understand it easily. There are no strict formatting requirements for this name.

### 4. Configure MCP <a href="#step-4-configure-mcp" id="step-4-configure-mcp"></a>

MaiAgent connects to remote MCP servers through URLs (supporting SSE and Streamable HTTP streaming protocols). It does not support MCP servers launched with local commands such as `npx` or `node`. In <mark style="color:blue;">MCP Configuration</mark>, you therefore only need to configure the server URL and authentication method. Any keys the server requires must be provided through headers or OAuth authorization.

First, check the MCP server's authentication method, then configure it using the following table:

| Server Authentication Method                                                    | How to Configure                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth login (users sign in to the external service and grant authorization)     | Select a connector under “<mark style="color:blue;">Select a Service to Connect</mark>”. See [b. OAuth Connectors and Authorization Scope](#oauth-connector)                                                                                         |
| A fixed API Key or Token (shared across the organization), or no authentication | Enter the URL under “<mark style="color:blue;">Or Enter Directly (No Authentication / Service Account)</mark>”. See [a. MCP Server URL](#mcp-server-url); enter the key in [c. Headers (JSON)](#mcp-headers)                                         |
| Each contact uses their own API Key or Token                                    | Create the tool as described in the previous row, then configure each contact's “<mark style="color:blue;">MCP Credentials</mark>” tab. See [Contact MCP Credential Settings](/maiagent-user-guide/en/build/tools/setup-contacts-mcp-credentials.md) |

#### a. 🔗MCP Server URL <a href="#mcp-server-url" id="mcp-server-url"></a>

* **Purpose**: The Agent uses this URL to connect to the MCP server, retrieve its tools, and call them.
* **Where to enter it**:
  * If the server uses OAuth: Click a connector card under “<mark style="color:blue;">Select a Service to Connect</mark>”, and the URL is filled in automatically. See [b. OAuth Connectors and Authorization Scope](#oauth-connector) below.
  * If the server requires no authentication or uses a fixed key: Paste the full URL, such as `https://mcp.example.com/mcp`, into the input field under “<mark style="color:blue;">Or Enter Directly (No Authentication / Service Account)</mark>”.
* **Format**: The URL must start with `https://` and point to a remote server accessible over the internet. You cannot save `localhost` or internal network addresses. For on-premises deployments that need access to an MCP server on an internal network, contact MaiAgent for assistance enabling access.
* **Note**: This field is required.

{% hint style="info" %}
For information on obtaining an MCP URL, see the [Technical Manual—Remote MCP Service Overview](https://docs.maiagent.ai/tech/mcp/remote-mcp).
{% endhint %}

{% hint style="info" %}
If the MCP server needs to identify the user in the current conversation: When visitors sign in to Web Chat with Keycloak, you can enable [Use the Keycloak Login Identity to Call Tools](/maiagent-user-guide/en/build/choose-channel/web-chat.md#keycloak-token-passthrough) in the channel settings and add this MCP server's host to the allowlist. The platform will pass the visitor's own Keycloak credentials in the `Authorization` header.
{% endhint %}

For tools with a directly entered URL, the system connects to the server using the URL and “<mark style="color:blue;">Headers (JSON)</mark>” when fetching the tool list under “<mark style="color:blue;">Allowed Tools (JSON Array)</mark>”. If the connection fails, the interface shows the reason, such as “<mark style="color:blue;">The MCP server returned HTTP 405. Check that the URL points to an MCP endpoint.</mark>” Follow the message to check the URL and headers. The system validates the connection again when saving. If it fails, you will see “<mark style="color:blue;">MCP tool validation failed. Unable to connect to the MCP server.</mark>” Tools that use an OAuth connector are saved first, and the tool list is fetched after authorization is complete.

#### b. 🔐 OAuth Connectors and Authorization Scope <a href="#oauth-connector" id="oauth-connector"></a>

When an MCP server uses OAuth, MaiAgent handles the authorization flow and automatically includes the access token in calls. You do not need to enter a key in the headers.

{% stepper %}
{% step %}

### Select a Connector <a href="#oauth-select-connector" id="oauth-select-connector"></a>

Under “<mark style="color:blue;">Select a Service to Connect</mark>”, click the card for the service you want to connect (marked <mark style="color:blue;">OAuth 2.0</mark>). The server URL is filled in automatically. The list includes services verified by the platform and custom connectors created by your organization.
{% endstep %}

{% step %}

### Create a Custom Connector If the Service Is Missing <a href="#oauth-custom-connector" id="oauth-custom-connector"></a>

Click the last card, “<mark style="color:blue;">Custom Connector Source</mark>”, fill in the following fields, and click “<mark style="color:blue;">Add Connector</mark>”. The system first tests whether it can connect to the server. On success, it returns to the card list and automatically selects the new connector.

| Field                                                | Required | Description                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Name</mark>                | Yes      | The connector identifier. It can contain only English letters, numbers, underscores, and hyphens, such as `my-mcp-server`                                                                                                                                                                                                                                      |
| <mark style="color:blue;">Display Name</mark>        | No       | The name shown on the card                                                                                                                                                                                                                                                                                                                                     |
| <mark style="color:blue;">Description</mark>         | No       | A brief description of what this MCP server does                                                                                                                                                                                                                                                                                                               |
| <mark style="color:blue;">Tool Category</mark>       | No       | The default category applied when tools from this server have no individual category. It affects the text displayed on tool cards in conversations                                                                                                                                                                                                             |
| <mark style="color:blue;">Logo</mark>                | No       | The card icon                                                                                                                                                                                                                                                                                                                                                  |
| <mark style="color:blue;">Server URL</mark>          | Yes      | The MCP server URL. It must use `https://`                                                                                                                                                                                                                                                                                                                     |
| <mark style="color:blue;">OAuth Server URL</mark>    | No       | The authorization server URL. If left blank, the system discovers it automatically from information published by the MCP server. Fill it in only if discovery fails or the authorization server and MCP server are on different domains (for example, Supabase's MCP server is at `mcp.supabase.com`, while its authorization server is at `api.supabase.com`) |
| <mark style="color:blue;">Resource Identifier</mark> | No       | The resource identifier specified when requesting a token from the authorization server. If left blank, it is detected automatically. Fill it in only if detection fails or the server publishes incorrect information (for example, Asana uses `https://mcp.asana.com`)                                                                                       |
| <mark style="color:blue;">OAuth Client ID</mark>     | No       | Leave blank if the server supports automatic client registration. Otherwise, create an application in the provider's OAuth service first, then enter the Client ID you receive here                                                                                                                                                                            |
| <mark style="color:blue;">OAuth Client Secret</mark> | No       | Used with the Client ID. Fill this in only if the provider requires a confidential client. If already configured, the field is masked. Leaving it blank retains the existing value; entering a new value replaces it                                                                                                                                           |

After creation, you can edit or delete the connector through “<mark style="color:blue;">Manage Connectors</mark>” on the “<mark style="color:blue;">Tools</mark>” page. Changing the “Server URL” revokes authorization for tools using this connector, so change it carefully.
{% endstep %}

{% step %}

### Select the Authorization Scope <a href="#oauth-auth-subject" id="oauth-auth-subject"></a>

After selecting a connector, choose whose account the Agent will use to operate the service under “<mark style="color:blue;">Authorization Scope</mark>”:

| Authorization Scope                                               | Description                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Organization Shared</mark>              | Everyone in the organization shares one authorization, granted once by an administrator or member. All users who interact through this Agent (LINE, Web Chat, etc.) then access the service using the authorizing person's account. Do not select this for personal account services where each person should use their own account |
| <mark style="color:blue;">Individual Contact Authorization</mark> | Each contact signs in and grants authorization separately in the conversation. The Agent acts as that contact. Users must be signed in: the Agent does not receive this tool in conversations with anonymous visitors who are not signed in                                                                                         |
| {% endstep %}                                                     |                                                                                                                                                                                                                                                                                                                                     |

{% step %}

### Complete Authorization <a href="#oauth-authorize" id="oauth-authorize"></a>

* **Organization Shared**: Click “<mark style="color:blue;">Authorize</mark>”. If the tool has not been saved yet, the system saves it first, then opens the external service's authorization window. After you sign in and grant consent, the interface shows “<mark style="color:blue;">Authorized</mark>”. The system automatically fetches and saves the tool list, then closes the editing window. To switch accounts, reopen the tool, click “<mark style="color:blue;">Revoke</mark>”, and authorize again.
* **Individual Contact Authorization**: No authorization is needed here. Each contact signs in and grants authorization in their own conversation. You can view or revoke authorization, or trigger reauthorization, in the “<mark style="color:blue;">Connector Authorization</mark>” tab of the “<mark style="color:blue;">Contacts</mark>” editing window.

{% hint style="warning" %}
The authorization window opens as a popup. If you see “<mark style="color:blue;">Popup blocked. Allow popups and try again.</mark>”, allow this site to open popups in your browser, then click “Authorize” again.
{% endhint %}
{% endstep %}
{% endstepper %}

#### c. 📰 Headers (JSON) <a href="#mcp-headers" id="mcp-headers"></a>

* **Purpose**: Set the HTTP headers included every time the system connects to the MCP server, such as a fixed API Key or Token.
* **Format**: A valid JSON object. Each key is a header name, and its value is the header content (a string). Keep `{}` if no headers are needed.
* **When entering a URL directly**: Enter the authentication headers required by the server here. Use the actual key value:

  ```json
  {
    "Authorization": "Bearer paste the token provided by the service provider here"
  }
  ```
* **When an OAuth connector is selected**: Authentication is handled automatically. Enter only additional custom headers here (optional). When the authorization scope is “Organization Shared”, do not enter `Authorization` here, as it will override the authorization added automatically.
* **Shared and individual credentials**: These headers are shared across all conversations. If each contact needs to use their own key, configure it for each contact in [Contact MCP Credentials](/maiagent-user-guide/en/build/tools/setup-contacts-mcp-credentials.md). When calling a tool, a contact's setting takes precedence for headers with the same name.
* **Available variables**: Values can use the variables listed under “<mark style="color:blue;">Available Context Variables</mark>” below the field (such as `{{contact_id}}` and `{{conversation_id}}`). The system substitutes the actual values for each conversation. Other `{{…}}` names are not substituted and cause an “<mark style="color:blue;">Contains unknown template variables</mark>” error when saving. You therefore cannot replace a key with a custom variable; enter the actual value.
* **Who can see them**: When you reopen the editing window after saving, each header value shows only its first and last 4 characters, with `****` in between. Saving without changes retains the original values. Headers are not provided to the AI model, and MCP tool execution logs do not store request headers.

### 5. Find “<mark style="color:blue;">Allowed Tools (JSON Array)</mark>” and Click Refetch <a href="#step-5-fetch-allowed-tools" id="step-5-fetch-allowed-tools"></a>

* **Purpose**: Specify the list of individual tools the Agent is authorized to use through this MCP client. An MCP client may provide multiple functions or individual tools.
* **Fetch and select tools**: Click “<mark style="color:blue;">Refetch</mark>” (or “<mark style="color:blue;">Fetch Tools</mark>” in the list if it has not been fetched before). The system connects using the current server URL and headers and lists all tools provided by the server. Use the switch to the right of each tool to choose which tools the Agent can use. You can also toggle all tools at once with “<mark style="color:blue;">Enable All</mark>” or “<mark style="color:blue;">Disable All</mark>”. At least one tool must be enabled before saving.
* **OAuth connectors**: When the authorization scope is “Organization Shared”, the system automatically fetches and saves the tool list after authorization is complete.

After you click, the system automatically retrieves the tools linked to that server and displays them in the list:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a71a8d1d54f524bfea21124d1732678c1956b626%2Fmcp-allowed-tools.png?alt=media" alt="Allowed Tools (JSON Array) section in the tool editing window, showing 3 / 3 tools enabled, Enable All and Disable All buttons, and a switch to the right of each tool; the Headers (JSON) values above are masked with ****"><figcaption><p>After fetching the tool list, use the switch to the right of each tool to choose which tools the Agent can use</p></figcaption></figure>

### 6. 💾 Save the Tool <a href="#step-6-save-tool" id="step-6-save-tool"></a>

After checking all settings, scroll to the bottom of the page and click the “<mark style="color:blue;">Confirm</mark>” button. Your new tool is now created!

When adding a tool, if you click <mark style="color:blue;">Confirm</mark> before opening the <mark style="color:blue;">Permission Settings</mark> tab, the tool will not be created yet. The interface automatically switches to <mark style="color:blue;">Permission Settings</mark> and displays “Please review the permission settings and confirm the assigned roles before submitting.” Under <mark style="color:blue;">Quick Permission Scope Selection</mark>, check which roles' members can use this tool (the default is <mark style="color:blue;">Exclude Default Roles</mark>), then click <mark style="color:blue;">Confirm</mark> again to create it. Organization-shared OAuth tools also go through this confirmation when you click “<mark style="color:blue;">Authorize</mark>”. This confirmation does not appear when editing an existing tool.

If the MCP server includes an interactive interface for a tool, a card you can interact with directly appears in the conversation after the Agent calls the tool. No additional configuration is needed. See [MCP Interactive Cards (MCP Apps)](/maiagent-user-guide/en/build/tools/mcp-apps.md).

## ⚠️ Important Notes <a href="#important-notes" id="important-notes"></a>

**Connection Testing**

* After creating a tool, test that the MCP connection works correctly
* You can verify tool functionality in a test environment

**Permission Management**

* Choose allowed tools carefully to avoid granting unnecessary capabilities
* Review tool usage regularly

**Troubleshooting**

* If the connection fails, check that the MCP server URL is correct
* Make sure “Headers (JSON)” is a valid JSON object and keys contain their actual values
* When using an OAuth connector (Organization Shared), check that the tool shows “<mark style="color:blue;">Authorized</mark>”


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/mcp-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.