Hosted MCP

Support reference for Alloy's hosted MCP endpoint.

Use **Hosted MCP** for this capability.

This name describes the product boundary: Alloy hosts an MCP server endpoint that external AI agents (Claude, Codex, Gemini, Cursor, etc) can connect to, to act as AI teammates with the scope controlled in Alloy. Avoid **Managed MCP** for this surface, because Alloy also manages outbound MCP server connections under `/mcps`; using Managed MCP for the hosted endpoint makes those two concepts easy to confuse.

Hosted MCP lets an external AI agent, such as Claude Desktop, Cursor, Codex, or another agent runtime, connect to a specific Alloy AI teammate through Alloy's `/mcp` endpoint.

From the client's point of view, Alloy is the MCP server. From Alloy's point of view, the request is executed as the selected AI teammate, scoped to:

- the organization - the AI teammate - the user who minted the token

This gives external agents one MCP connection that can expose the teammate's approved Alloy tools, skills, and assigned upstream MCP toolsets.

Hosted MCP and `/mcps` are different surfaces:

- `/mcps` registers outbound MCP servers that Alloy AI teammates can call. - Hosted MCP exposes an Alloy AI teammate as an inbound MCP server for external AI agents.

If an AI teammate has an upstream MCP assigned in `/mcps`, Hosted MCP can expose that upstream toolset through Alloy's hosted endpoint. The external client does not need to configure every upstream MCP separately.

AI teammate detail pages include a `PATs` tab.

From that tab, a user can:

- create a bearer token for the current AI teammate - copy the generated MCP client configuration - list that user's tokens for the teammate - delete a token

Token routes:

- `GET /api/organizations/{orgId}/employees/{employee_id}/mcp-tokens` - `POST /api/organizations/{orgId}/employees/{employee_id}/mcp-tokens` - `DELETE /api/organizations/{orgId}/employees/{employee_id}/mcp-tokens/{token_id}`

These token-management routes are human-only and are not exposed as AI-callable organization actions.

Current create-token behavior:

- create returns a ready-to-paste MCP client JSON config string - the generated config currently points `mcp-remote@latest` at `{api_url}/mcp` - the generated config currently uses `alloy` as the `mcpServers` entry name - the generated config sends the bearer credential through an `Authorization` header and environment variable placeholder - the plaintext token is shown only once in the create dialog and is not recoverable later from the list view

Hosted MCP is served at:

```text {api_url}/mcp ```

Authentication accepts either:

- `Authorization: Bearer <token>` - `api-key: <token>`

The token resolves the organization, employee, and user context before any tools are registered. Requests without a valid token return `401`.

The current endpoint uses MCP Streamable HTTP. Clients send MCP JSON-RPC requests with `POST /mcp`. `GET /mcp` returns `405 Method Not Allowed`; there is no separate GET-driven SSE stream.

The current implementation is stateless per request:

- each request builds a fresh MCP transport and server instance - Alloy tears down that transport/server pair when the HTTP response closes

For each authenticated request, Alloy builds a fresh MCP server and registers:

- the AI teammate's approved Alloy MCP-server tools - the AI teammate's skills - assigned outbound MCP and OAuth MCP toolsets

Assigned upstream MCP toolsets are exposed through the hosted Alloy endpoint with namespaced tool names:

```text {toolsetName}__{toolName} ```

This avoids collisions when multiple upstream MCP servers expose tools with the same name.

- Treat MCP tokens as bearer credentials. - Delete an MCP token to immediately revoke access for clients using it. - Token list responses return obfuscated token values. - The full plaintext token is only available in the generated configuration returned by the create-token flow. - Hosted MCP access follows the selected AI teammate's configured tools, skills, storage permissions, and MCP assignments.