Custom MCP Servers

Cosmo ships with a curated set of integrations, but any MCP server your team runs can be added to your organization directly — no Cosmo release required. Once registered, a custom server behaves like any other connector: connect it, and its tools become available to the model in chat.

Tools from a custom server are always prefixed with the server's identifier (acme-crm__search), so two servers offering a similarly named tool stay distinct.

Requirements

Local (STDIO) MCP servers — the kind launched with a command like npx some-server — are not supported. Running an arbitrary command supplied through a settings form would be code execution on every member's machine.

Authentication options

Adding a server

1. Open Integrations from the sidebar.
2. Click Custom MCP server in the Add new integration section.
3. Fill in:
   • Name — what members see in the list, e.g. Acme CRM.
   • Identifier — a slug, auto-derived from the name. Lowercase letters, digits and hyphens. It cannot be changed later, and cannot match a built-in Cosmo connector.
   • Server URL — the MCP endpoint, e.g. https://mcp.acme.com/v1/mcp.
   • Transport and Authentication as above.
4. Click Add server. Cosmo registers the server and immediately connects it.

The server then appears in the integrations list with a Custom badge, so anyone in the org can tell it apart from a Cosmo-vetted integration.

What happens when you click Add server

Cosmo opens a real connection to the URL you gave it before saving anything. The address has to answer as an MCP server — a site that merely loads in a browser is not enough, and neither is a URL with a typo in it.

Registering the server and connecting it succeed or fail together. If the connection does not succeed the registration is undone, so a server that could not be reached leaves nothing behind — no entry in the list, nothing to remove by hand. You will not end up with a connector that says Connected but has no tools behind it.

This check takes a few seconds at most. If the server does not respond within ten seconds Cosmo gives up and tells you so, rather than leaving the panel waiting.

Connecting additional accounts

Custom servers support multiple connections, same as built-in ones — click Add another and give the connection a label. For an API-key server you supply the token again, because the token belongs to the connection, not to the server definition.

Editing a server

Registered servers can be renamed after the fact — click Edit on the custom entry in the Add new integration list and change:

• Name — what members see in the integrations list.
• Description — the one-line summary shown under the name.

Both changes apply to the whole organization, not just to you, and take effect the next time members load their integrations list.

Only the name and description are editable. The identifier, server URL, transport and authentication mode are fixed once the server is registered: existing connections pin the URL they were created against, so changing it would silently repoint them — and send credentials a member entered for one host to another. To move a server to a new endpoint, remove it and register it again.

Editing is limited to organization owners and admins, same as registering and removing.

Renaming a connection

The name on a connection is separate from the server's own name, and it is what tells two accounts of the same provider apart. Click the connection's label in the Connected list to rename it in place — useful for fixing a typo, which previously meant disconnecting and reconnecting the account. This renames only your own connection; other members' connections to the same server are untouched. It applies to every connector, not just custom ones.

Removing a server

Registering and removing custom servers is limited to organization owners and admins. Members see and connect the servers an admin has registered, but not the Custom MCP server or Remove server controls.

Click Remove server on the custom entry. This deletes the server definition, every connection to it in your organization, and any stored credentials. Removing a server affects all members, not just you.

Limits and troubleshooting

• An organization can register up to 25 custom servers.
• A custom server may expose up to 60 tools. Beyond that the extra tools are ignored — they are not available to the model.
• Tool names must use only letters, digits, _ and -. A tool whose name contains anything else (a space, a dot, a parenthesis) is skipped, as is one whose name is still longer than 128 characters after the server prefix is added. Everything else from that server keeps working. If a tool you expect is missing, a shorter or simpler tool name on the server side is usually the fix — and a shorter slug leaves more room for long tool names.
• "Could not connect to ... please check the configurations" means the address did not complete the MCP handshake. The server is not added — the registration is undone, so there is nothing to clean up and no half-finished entry in the list. The form stays open with your details, so correct and resubmit. Check, in this order: the Server URL (most servers expose MCP on a path such as /mcp or /sse, not at the site root — a plain website address will not work), the Transport, and the Authentication settings.
• If an already-added server later becomes unreachable or rejects the credentials, the connection shows an Error badge with the reason in the integrations list, and its tools are absent from chat. Other connectors are unaffected. The next chat message retries the connection, so fixing the server or re-entering the key clears the error without removing anything.
• A server that does not respond within 30 seconds is treated as unreachable rather than holding up the rest of your integrations.
• A slug that collides with a built-in connector (notion, google, slack, …) is rejected. Choose a different identifier.
• Custom servers connect from the desktop app. Tools from a custom server are not yet available in cloud-only contexts.