# MCP Servers

### Understanding MCP Server Integration in Appmixer

In Appmixer, MCP servers can only be connected to **dedicated mcp ports** of AI Agent components. This restriction ensures that AI Agents can communicate with MCP servers through a controlled and consistent interface.

<figure><img src="/files/9G09hYj62SGzzNSRWxyZ" alt=""><figcaption></figcaption></figure>

***

### MCP Server Connector Components

Every MCP server connector in Appmixer is composed of three distinct components:

| **Component** | **Purpose**                                                                         | **Where it’s used**                                                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCPServer** | Core component that provides the actual MCP server connection and tool definitions. | Can be connected only to AI Agent component’s mcp port.                                                                                              |
| **ListTools** | Helper component that lists all available tools exposed by the MCP server.          | Used internally by MCPServer (not standalone).                                                                                                       |
| **CallTool**  | Helper component to invoke a specific tool from the MCP server.                     | Used internally by MCPServer and can also be used standalone in regular flows to call a selected tool, similar to an action-type Appmixer component. |

Important:

* The **AI Agent component** `mcp` port can connect **only** to *MCPServer* components.
* *ListTools* and *CallTool* are *helper* components for the *MCPServer*, but *CallTool* has the added ability to be used independently in non-AI Agent flows.

***

### How to Implement a Custom MCP Server Connector<br>

To integrate your own MCP server, you will create an **Appmixer connector** that wraps your server code, following the structure of existing MCP server connectors in our public repository.

#### Step 1 – Start from an Existing Example

Use one of our open-source MCP server connectors as a template:

* Repository: [appmixer-connectors/src/appmixer/mcpservers](https://github.com/clientIO/appmixer-connectors/tree/dev/src/appmixer/mcpservers)
* Example: [GitLab MCP Server Connector](https://github.com/clientIO/appmixer-connectors/tree/dev/src/appmixer/mcpservers/modelcontextprotocol_server_gitlab)

The complete list of files of our Gitlab MCP Server connector looks like this:

```
mcpservers/modelcontextprotocol_server_gitlab/
├── CallTool
│   ├── CallTool.js
│   └── component.json
├── ListTools
│   ├── ListTools.js
│   └── component.json
├── MCPServer
│   ├── MCPServer.js
│   └── component.json
├── auth.js
├── bundle.json
├── lib.js
├── module.json
└── package.json
```

> Note: The GitLab example assumes that your MCP server uses the Stdio-style implementation of the MCP protocol. If your MCP server uses a different communication method, you may need to adjust the connector logic accordingly.

#### Step 2 – Files to Modify

From the example connector, most files are generic and can be reused. You only need to modify:

1. **lib.js**
   * Points to the NPM package containing your MCP server. Your MCP server must be NodeJS based.\
     \&#xNAN;*If you do not have a public NPM package with your MCP server, you can also package the MCP server directory directly in the Appmixer connector. Just make sure to reflect this in the paths.*
   * Replace GitLab-specific logic with your own (if you used a different existing MCP server as a foundation, replace that MCP's specific logic with your own).
   * Ensure your MCP server package is listed in `package.json` dependencies\
     \&#xNAN;*(Unless you package your MCP server directly in the Appmixer connector directory, see above.)*
2. **auth.js**
   * Define any required environment variables (API keys, credentials) for your MCP server.
   * These will be shown to the user in Appmixer Designer when they configure the connector.
3. **Manifest & Metadata Files**
   * **package.json**
     * Name following convention: `appmixer.mcpservers.<your_mcp_server_name>`
     * Add your public MCP server NPM package under dependencies.
   * **module.json, bundle.json**
     * Update name (use the same one as above, i.e. in the `package.json` file), label, description, and icons.
   * **CallTool/component.json, ListTools/component.json, MCPServer/component.json**
     * Update the name to follow the convention above (e.g., `appmixer.mcpservers.your_mcp.CallTool`).
     * Update `auth.service` section to match your connector name (e.g., `appmixer:mcpservers:your_mcp`).
     * Replace all occurrences of the GitLab connector path with your connector path.
     * Set your custom icon.

**You generally do NOT need to edit**:

* `MCPServer/MCPServer.js`
* `ListTools/ListTools.js`
* `CallTool/CallTool.js`

\
These files contain generic logic that works for all MCP servers.

***

### Packaging and Publishing

Once you have updated the connector, follow the standard instructions to pack and publish your connector to your Appmixer tenant as described [here](/6.0/6.3/getting-started/custom-connectors.md#publish-your-component).&#x20;

```
appmixer pack appmixer/mcpservers/your_mcp_server
appmixer publish appmixer.mcpservers.your_mcp_server.zip
```

***

### Summary Checklist

\
Before publishing:

* Updated `package.json` with correct name and NPM MCP server dependency.
* Updated `module.json`, `bundle.json` with correct name, metadata and icons.
* Edited `lib.js` to point to your MCP server code.
* Configured `auth.js` with required authentication fields.
* Updated `component.json` files for all three components.
* Tested `CallTool` both as helper and standalone in a flow.
* Connected `MCPServer` to an AI Agent `mcp` port and verified tool discovery.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appmixer.com/6.0/6.3/building-connectors/mcp-servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.