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`
`Outlook Mail`
`Outlook Calendar`
`OneDrive`
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 use `POST /api/organizations/{orgId}/mcps/test`.
The request body requires:
`employee_id`: the AI teammate UUID whose connector context should be tested
exactly one of `mcp_id` or `oauth_mcp`
Supplying neither connector identifier or both identifiers fails request validation.

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`
OAuth connector rows are grouped by provider service, currently `Google` and `Microsoft`.
The Connectors tab is also where users connect, validate, reconnect, or disconnect the OAuth account for that specific AI teammate.
Current connected-state UI can show:
status badge `Valid`, `Invalid`, or `Unknown`
`Connected by {user}`
connected account identifier when available, such as Google email or OAuth user id
OAuth MCP checkboxes stay disabled until the matching service is connected for that teammate.
Completing or repeating a Google or Microsoft OAuth connection automatically assigns all OAuth MCPs provided by that service.
Disconnecting that OAuth service removes its integration and matching OAuth MCP assignments transactionally.
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.
The bundled Gmail OAuth MCP uses its extended tool tier. It supports reading and composing Gmail messages, creating drafts, and modifying message state such as marking messages as read when the connected Google authorization includes the required scope.
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.