> 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, short for Model Context Protocol, can integrate services across multiple cloud platforms or run local client applications.

Think of tool use as a plug: you need to plug it in and supply power before you can use a service. Traditionally, each LLM develops its own approach to using tools. Like plugs with different specifications, these approaches require different sockets. To let both OpenAI and Claude use Google Calendar, developers need to create multiple scripts for different AI systems.

When Google Calendar updates, developers may need to:

1. Update 3 different versions of the integration at the same time
2. Maintain 3 separate sets of technical documentation

This increases development time and costs.

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

MCP is a standardized protocol designed to solve this problem. It simplifies development through:

1. A standardized format for tool definitions
2. A unified communication protocol
3. Consistent error handling

These mechanisms streamline the development process.

With MCP, developing a tool only requires the following:

1. Create an MCP Server (develop once)
2. Define standardized tool specifications
3. Implement unified business logic
4. Make it available to all AI platforms that support MCP

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0e7f13f7d59130a0b84c569ec1e913694500768a%2Fplayma%20(9).png?alt=media" alt=""><figcaption><p>Comparison before and after MCP integration</p></figcaption></figure>

MCP is fundamentally a protocol designed to **standardize AI tool integration**. It enables development teams to “<mark style="color:blue;">develop once, use everywhere</mark>,” significantly reducing the complexity and maintenance costs of the AI assistant tool ecosystem.

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

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

First, open the “ <mark style="color:blue;">AI Features</mark>” section in the left navigation bar, then click “<mark style="color:blue;">🔧 Tools</mark>.” On the tool list page, click the “<mark style="color:blue;">➕ Add Tool</mark>” button in the upper-right corner.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-dd5576c2a8c64ec454893eb5c08dcae07b072918%2FMCP%E5%B7%A5%E5%85%B7%20(1).png?alt=media" alt="Tool list page and Add button"><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.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-21f5fad84196cbd53b9cbadbfc800bc6bf91cace%2FMCP%E5%B7%A5%E5%85%B7%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>

### 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>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e8c3fa5bce7f8f1fb3ca523bded8c98c302ccaf1%2FMCP%E5%B7%A5%E5%85%B7%20(3).png?alt=media" alt=""><figcaption></figcaption></figure>

* **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>

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

* **Purpose**: MaiAgent currently supports external MCP servers. Providing the MCP server's service URL lets the AI assistant call MCP services to connect to external applications.
* **Format**:
  * Enter the complete URL (for example, `https://mcp.dev/maiagent/mcp_service`).
* **Note**: This field is required.

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

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

Paste your MCP server URL here. The system will automatically retrieve the list of tools connected to that server:

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-62093033fa0e37063fdd1a0caa7b36b45e847b9f%2FMCP%E5%B7%A5%E5%85%B7%20(4).png?alt=media" alt=""><figcaption></figcaption></figure>

#### b. 🎛️ MCP Command Arguments (mcp\_args) <a href="#mcp-args" id="mcp-args"></a>

{% hint style="warning" %}
If you do not need to configure specific environment variables, you can leave this field blank.
{% endhint %}

* **Purpose**: Define the argument names to pass when running MCP commands or calling MCP services. The AI assistant generates the contents automatically.
* **Format**: A JSON array is recommended, with each element being a string representing an argument.
  * **Example** (JSON array):

    ```json
    [
        "--user",
        "admin",
        "--config",
        "/path/to/config.yaml"
    ]
    ```
  * **During execution**: The AI assistant passes these arguments to the MCP tool in order
  * If you enter a comma-separated string (for example, `arg1,arg2,arg3`), the system will try to parse it as an argument list. Use a JSON array to avoid ambiguity.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a965eab143b54049703197d49a7dc6479b562056%2FMCP%E5%B7%A5%E5%85%B7%20(5).png?alt=media" alt="MCP command argument configuration example"><figcaption><p>Configure MCP command arguments</p></figcaption></figure>

#### c. 🌳 MCP Environment Variables (mcp\_env) <a href="#mcp-env" id="mcp-env"></a>

{% hint style="warning" %}
If you do not need to configure specific environment variables, you can leave this field blank.
{% endhint %}

* **Purpose**: Set the environment variables required to run MCP commands.
* **Format**: Use a valid JSON object. Each key is an environment variable name, and each value is the environment variable's content (a string).
  * **Example**:

    ```json
    {
      "API_KEY": "{{SECRET_MCP_API_KEY}}",
      "REGION": "us-west-1",
      "DEBUG_MODE": "true"
    } 
    ```

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-14cb970b83ae5611c86b25508ccdeabc052e120d%2FMCP%E5%B7%A5%E5%85%B7%20(6).png?alt=media" alt="MCP environment variable configuration example"><figcaption><p>Configure MCP environment variables</p></figcaption></figure>

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

* **Purpose**: Specify the list of individual tools that the AI assistant is authorized to use through this MCP client. An MCP client may provide multiple functions or individual tools.
* **Automatic detection / Leave blank**: If this field is blank or omitted, the system will try to detect all available tools when it first connects to the MCP client and allow all detected tools by default. To restrict the AI assistant to specific tools, list them explicitly here.

After you click, the system automatically retrieves the tools connected 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-3b8a4967a0e6681a061212c15ff364f3be30e48c%2FMCP%E5%B7%A5%E5%85%B7%20(7).png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-cdb6eda7289d961c6228647418f17eee69a0e801%2Fimage%20(113).png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3eb68a486703debfc7142bb3afb4404e255076da%2FMCP%E5%B7%A5%E5%85%B7%20(8).png?alt=media" alt=""><figcaption><p>Tool names defined in MCP</p></figcaption></figure>

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

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

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-15e837afde2b4925f1e73faf41021e7d81b2fee5%2FMCP%E5%B7%A5%E5%85%B7%20(9).png?alt=media" alt=""><figcaption></figcaption></figure>

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

**Connection Testing**

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

**Permission Management**

* Choose allowed tools carefully to avoid authorizing unnecessary functions
* Review tool usage regularly

**Troubleshooting**

* If the connection fails, check that the MCP server URL is correct
* Ensure that environment variables and argument formats meet the requirements


---

# 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.