Skip to content
Docs menu

Your organisation's MCP servers

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.

View .md

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

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

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

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

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

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

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 for the reasoning.