---
title: Your organisation's MCP servers
description: Add your own MCP servers by URL for everyone in the organisation, test the connection, choose whether the cloud or only your venom clients reach them, and keep credentials sealed.
section: cloud
order: 64
audience: [user, operator, builder, agent]
sources: [services/nodejs-cloud/app/(console)/(shell)/mcp, services/nodejs-cloud/lib/mcp-custom, services/nodejs-cloud/app/api/admin/v1/mcp-servers, services/nodejs-cloud/lib/orgs/mcp-mcpservers.ts, docs/adr/0085-custom-mcp-servers.md]
features: [cloud.api-admin-mcp-servers]
---

The **MCP** page (`/mcp`) lists the curated catalog and the servers your organisation approved. **Your organisation's servers**
is where an owner or admin adds an MCP server of their own, once, for the whole organisation: an internal docs search, a
ticket system, a data gateway. Members and venom clients get it like a catalog server, and the cloud's agent chats can use it
when the cloud can reach it.

Only owners and admins add, change, test or remove a server. Members with access to the page see the list.

## Add a server {#add}

Choose **Add server**, or paste a config first.

- **Name**: letters, digits, `-` and `_`. It is what members type in `venom mcp enable <name>`. It cannot be a catalog or Venom server's name.
- **Title, description, icon**: what members see. The icon is one letter or emoji.
- **Reachable from**: see below.
- **URL**: the server's MCP endpoint (Streamable HTTP), often ending in `/mcp`. No user name, password or `#fragment`, and no
  credential in the query (`?token=…` is refused: the address is shown to every member).
- **Sign-in**: see below.
- **Key groups**: tick the key groups that get it; none ticked means all of them.
- **On for every member by default**: otherwise it is available and members turn it on.

**Paste a config.** Paste a standard MCP JSON config, `{"mcpServers": {"docs": {"url": "https://…", "headers": {…}}}}` (the
`servers` key of VS Code and a single server object work too). The first server fills the form; nothing is saved until you
press Save. An entry with a `command` (stdio) is refused: the cloud cannot run local commands, so run it where your members work
or put it behind an https MCP endpoint.

## Reachable from {#reach}

| | Cloud and clients | Clients only |
|---|---|---|
| Address | a public https URL | a private or internal URL; http is allowed |
| The cloud calls it | yes: it tests it, and agent chats use it | never |
| Test connection | yes | no: the page says why |
| Agent chats | offered, as `custom:<id>` | not offered |
| Venom clients | get it through the signed policy | get it through the signed policy and connect from inside your network |

The cloud keeps refusing private, loopback, link-local and metadata addresses, however they are written or resolved. If you pick
*Cloud and clients* for a private address, the form refuses it and suggests *Clients only*. Relaying a *Clients only* server through
your daemon, so the cloud could use it, is not available yet. SSE servers can be added as *Clients only*.

## Sign-in {#auth}

| Mode | Who holds the credential |
|---|---|
| No sign-in | nobody |
| One org-wide token or headers | the vault: sealed, write-only. The page shows only the header names that are set, never a value. Cloud reach only: the secret is never sent to venom clients |
| Each member signs in (OAuth) | each member, at the server. The cloud finds the server's sign-in page, registers itself and uses PKCE, as for catalog servers |
| Each member gives their own token | each member, sealed in their own connection; entered through `POST /api/workspace/agents/connections` with `server` and `token` (the Agents picker has no field for it yet) |

A policy is readable by every member, so it carries the address and whether the server uses OAuth, never a token or a header. Venom
clients sign in or use the member's own credentials themselves. Editing a server that has a stored secret and changing its address
asks for the token or headers again, so an edit cannot quietly send them to another host. Leave both empty on an edit to keep the stored
secret; fill either to replace it.

## Test connection {#test}

*Test connection* runs `initialize` and `tools/list` and shows the server's name and version, the number of tools and their names,
or one precise reason it failed: the address is refused, the host does not resolve, the TLS certificate is not accepted, the connection
was refused, a timeout (15 seconds), 401, 403, a redirect (never followed: use the final address), another status, or "not an MCP
server". A server that asks each member to sign in answers 401 to the cloud; that shows as reachable. The last result and its time are
kept on the server. What a server says about itself is shown as plain text, cleaned and cut to length.

## How it reaches people {#delivery}

Each key group's signed policy carries the servers in its scope in `mcp.servers` and `mcp.allow`, so one list governs both venom
clients and agent chats. A server you add is allowed for the organisation by default. Turn it off, or remove it, and it leaves
every policy; the other servers in a key group's registry are never touched. Members get the change when venom starts or with
`venom policy sync`. Without policy signing set up (the page has a button), the server still works for the cloud's own use and venom
clients wait for signing.

A key group that has no MCP section allows every server. The first server added gives it one, whose `allow` list is that server: from
then on, only listed servers may start, as when you approve the first catalog server.

**Private http addresses are held for now.** The signed policy accepts `https:` addresses, and `http:` only to loopback. A *Clients only* server with an `https:` address (an internal name on a corporate certificate, say) is delivered to venom clients now and works with every client. A *Clients only* server with a plain `http:` address can be saved here, and the form checks it is on a private network (`10.x.x.x`, `172.16.x.x` to `172.31.x.x`, `192.168.x.x`, a name such as `mcp-gateway` or `tools.corp`, or a `.internal`, `.local`, `.lan`, `.corp`, `.intranet` or `.localdomain` name; numeric and hex hosts such as `134744072` are refused because URL parsers read them as public addresses). It is always held out of the signed policy: its row says "Not sent to venom clients yet", and the API shows `venom_clients: "held"`. Delivering plain-http internal servers needs a change to the venom CLI's policy parser that is awaiting the owner's approval; until it ships, members can add the server in their own `.mcp.json`.

A venom CLI built before that change rejects the whole policy when one server has an address it does not accept, so the cloud never writes a non-loopback http address into a policy.

## Audit {#audit}

`mcp_servers.created`, `updated`, `enabled`, `disabled`, `removed` and `tested` go in the audit log with the name, the address without
its query, the reach, the sign-in mode, the header names and what changed. Never a value.

## API and MCP tools {#api}

| Route | Tool | What it does |
|---|---|---|
| `GET /api/admin/v1/mcp-servers` | `admin_mcpserver_list` | the organisation's servers and their last test |
| `GET /api/admin/v1/mcp-servers/{id}` | `admin_mcpserver_get` | one server |
| `POST /api/admin/v1/mcp-servers` | `admin_mcpserver_create` | add one (`name`, `url`, `title`, `description`, `icon`, `reach`, `auth`, `default_on`, `enabled`, `team_ids`; the REST route also takes `token` and `headers`) |
| `PATCH /api/admin/v1/mcp-servers/{id}` | `admin_mcpserver_update` | change, enable or disable, rescope |
| `DELETE /api/admin/v1/mcp-servers/{id}` | `admin_mcpserver_delete` | remove it with its secret and every member's connection |
| `POST /api/admin/v1/mcp-servers/test` | `admin_mcpserver_test` | test an address before saving it (`url`, `reach`, `auth`; REST also `token` and `headers`) |
| `POST /api/admin/v1/mcp-servers/{id}/test` | `admin_mcpserver_test` with `server` | test a saved server with its stored credentials |

Changing needs the `org:manage` permission; reading needs `routing:read`. Responses never contain a secret, and **no MCP tool takes
one**: an org-wide token or headers are entered by a person in the console or over REST. An agent can add servers that need no
org-wide secret and test any server.

See [ADR 0085](/docs/reference/adr.md) for the reasoning.
