> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/workspace/integrations/custom-mcp.md).

# Custom MCP

Custom MCP servers let you extend nexos.ai with your own tools, APIs, and workflows. Instead of waiting for pre-built integrations, you can connect internal systems, proprietary tools, or specialized workflows directly to nexos.ai.

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2FkUQkwYdAg8NHeRbQvx5w%2FScreenRecording2026-09-25at16.56.55-ezgif.com-video-to-gif-converter.gif?alt=media&amp;token=05f44a55-66f9-4aa7-8efe-660afbf67cda" alt="" width="563"><figcaption></figcaption></figure>

### What is Custom MCP?

Custom MCP stands for Model Context Protocol. It is a standardized way to connect external tools and data sources to AI models. By adding a custom MCP server, you give nexos.ai access to your tools without needing a pre-built connector.

### When to use Custom MCP

Use Custom MCP when you need to:

* connect internal tools or proprietary systems
* integrate specialized workflows not available as standard integrations
* connect legacy systems or custom databases
* build integrations specific to your team's workflow
* extend nexos.ai with custom logic or actions

### How it works

1. You set up or provide a custom MCP server (either hosted by you or by a third party).
2. You add the server details to nexos.ai from the Apps page.
3. nexos.ai connects to your MCP server and gains access to the tools it exposes.
4. You can then use those tools in Chat and Agents just like standard integrations.

### How to add a custom MCP server

{% stepper %}
{% step %}

### Get your MCP server details

First, you need a running MCP server. This could be:

* a server you or your team built
* a third-party MCP server hosted externally
* a managed MCP service

You will need:

* the **server URL** (where the MCP server is running)
* **authentication details** if required (API key, credentials, etc.)
* any **configuration parameters** the server needs
  {% endstep %}

{% step %}

### Add the custom MCP to nexos.ai

* Open **Management**.
* Go to **Apps**.
* Select **Add custom MCP** (next to the list of the integrations.).
* Fill in the server details:
  * **Server name** — a name for this custom MCP (e.g., "Internal CRM")
  * **Server URL** — the URL where your MCP server is running
  * **Authentication** — API keys, credentials, or other auth details if required. Each user will be able to provide their own API key individually once the server is connected
  * **Configuration** — any additional settings the server needs
* Select **Test connection** to verify the server is reachable.
* Select **Save** to add the custom MCP.
  {% endstep %}

{% step %}

### Use the custom MCP

Once added, your custom MCP appears in the integrations list with a status of **Active**. You can now:

* enable it in Chat from the **Tools** panel
* add it to Agents in **Agent Settings → Integrations**
* use it like any other integration in your workflows
  {% endstep %}
  {% endstepper %}

{% hint style="info" %}
**Important notes**

* **Authentication** – make sure your MCP server is secure and your nexos.ai workspace has the correct credentials to access it
* **Server availability** – your MCP server must be running and reachable from nexos.ai at all times
* **Whitelisting** – if you need to whitelist nexos.ai IPs to allow access to your server, contact us.
* **Testing** – always test your custom MCP connection before relying on it in production
* **Support** – if your custom MCP stops working, check that the server is running and the connection details are still valid
* **Updates** – if you update your MCP server, you may need to update the configuration in nexos.ai
* **Connection type** – nexos.ai currently supports only streamable HTTP. This means your MCP server must be hosted at a URL reachable over the internet, rather than running as a local file or process.
  {% endhint %}

### Troubleshooting

#### Connection failed

* Verify the server URL is correct and reachable
* Check that any required authentication credentials are valid
* Make sure your firewall or network allows nexos.ai to connect to the server

#### Tools not appearing

* Verify the MCP server is running and responding
* Check that the server is properly configured to expose tools
* Try testing the connection again from the integrations page

#### Errors when using the custom MCP

* Check the error message for details about what failed
* Verify the server has the required data or permissions to complete the action
* Contact your MCP server administrator if the issue persists

### FAQ

**Can I add multiple custom MCP servers?**\
Yes. You can add as many custom MCP servers as you need. Each one appears in the integrations list.

**What happens if my MCP server goes down?**\
nexos.ai will show an error when you try to use that integration. Once the server is back online, the integration will work again.

**Can I edit a custom MCP after adding it?**\
Yes. You can update the server URL, authentication, and configuration from the integrations list. Select the custom MCP and choose **Edit**.

**Can I share a custom MCP with other teams?**\
Custom MCP servers are added at the organization level, so all teams and members in your workspace can use them once enabled.

**What if I want to remove a custom MCP?**\
You can deactivate it from the integrations list or delete it entirely. Deactivating keeps the configuration saved in case you want to re-enable it later.


---

# 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.nexos.ai/workspace/integrations/custom-mcp.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.