Technical docs

MCP Servers

Overview

Support reference for org connector management at `/mcps`.

For the inbound MCP endpoint that lets external clients (Claude, Codex, Gemini, etc) connect to an Alloy AI teammate, see `hosted-mcp.md`.

Registers connectors at the organization level.
Lets staff enable or disable those connectors per AI teammate from the AI teammate detail view.
Supports both:
`simple` MCP servers configured by URL and optional headers
predefined `oauth` MCP entries backed by connected user integrations

Route metadata title: `Connectors`.
Page card title: `Connectors`.
Page description: `Connect external systems and services to your AI Teammates`.
Primary action: `Add`.
Empty state: `No connectors`.
Table columns: `Name`, `Type`, `URL / OAuth`, `Headers`, `Added`, `Updated`.
Row actions: `Test`, `Edit`, `Delete`.
Bulk action: `Delete`.
Predefined OAuth MCP rows are always shown at the top of the table and are not selectable for bulk delete.
Current predefined OAuth MCP rows are:
`Gmail`
`Google Calendar`
`Google Drive`
If a predefined OAuth MCP is missing its required OAuth connection, the table shows a warning icon that links to `/integrations`.

Create dialog fields:
required `Name`
required `URL`
optional header key/value pairs
Create dialog title: `Add Connector`.
Create currently creates `simple` MCP servers only.
The create dialog only accepts `http://` and `https://` URLs.
The create dialog blocks duplicate names against the currently loaded org list, and the backend create action also rejects duplicate names.
Edit dialog behavior:
title: `Edit Connector`
description: `Update the connector configuration`
shows immutable type badge: `Simple (HTTP URL)` or `OAuth`
`Type cannot be changed. Recreate the connector to switch type.`
simple MCPs can edit `Name`, `URL`, and headers
oauth MCPs can edit `Name` and the selected `oauth_mcp`
Backend notes:
create/update accept `type`, `url`, `headers`, and `oauth_mcp`
`name` uniqueness is enforced by the database on `(organization_id, name)`

Testing starts automatically when the dialog opens.
Dialog title: `Test Connector`.
The current dialog shows:
success or error state
connected toolset names
per-toolset tool counts
tool badges
Success badge format: `Connected · {n} tools`.
Error payload is shown as plain text in the dialog.
Test requests now use `POST /api/organizations/{orgId}/mcps/test` with exactly one of:
`mcp_id`
`oauth_mcp`

AI teammate detail pages include a `Connectors` tab, described in the UI as `Connected systems and services`.
The tab lists both org `simple` MCP servers and predefined OAuth MCPs.
The current tab reads enabled assignments through `GET /api/organizations/{orgId}/mcps/employee/{employee_id}`.
Checking a box assigns that MCP to the teammate.
Unchecking a box removes the assignment.
Assignment/unassignment accepts exactly one of:
`mcp_id`
`oauth_mcp`
If an OAuth MCP requires Google and that integration is not connected for the current user, the tab shows a warning with a `Go to integrations →` link.
The checkbox flow is optimistic in the frontend.
If there are no assignable rows, the tab empty state says `No connectors` and tells users to add connectors in organization settings first.

Assigned MCP servers are loaded per AI teammate by `MCPBuilder`.
OAuth MCP definitions currently come from `OAuthMCPProvider` in the backend.
Runtime URL and header values go through organization-variable injection before the client is built for `simple` MCPs.
MCP list/create/get/update/test and assignment routes are AI-accessible through `system.do_organization_action`.
MCP delete remains human-only (`availableToAI: false`).
There is no websocket sync for MCP CRUD in the current org page; the frontend relies on React Query invalidation and refetches.