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, workflows, 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 currently 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 Alloy MCP-server tools: its configured tool list plus the tools its workspace and employee type add, filtered to the hosted catalog
• the AI teammate's workflows
• assigned outbound MCP and OAuth MCP toolsets
• workspace skill tools when the teammate has a Storage-backed skills workspace: `skill`, `skill_search`, and `skill_read`

In `tools/list` responses, Alloy removes the `$schema` keyword recursively from each tool's input and output schema while preserving the remaining schema structure. Clients can therefore apply their own JSON Schema validator dialect instead of rejecting a tool because the schema advertises a different draft.

That widening matches how a run widens the same list: `storage.*` tools are added when the teammate has a Storage workspace (at least one shared folder, or any system teammate), and the system workflow and employee tools are added for a system teammate, including the workflow-run readers and `system.export_workflow_run_step_log`. A connection has no conversation, so conversation-scoped tools are never added, and tools outside the hosted catalog (`agent.call_teammate`, for example) are not exposed.

The MCP initialize response tells the connecting client that it is operating as an AI teammate under the deployment's configured brand name and points it to the `work-with-alloy` skill repository. The brand name defaults to `Alloy`.

The same initialize instructions also include:

• the selected teammate's resolved text-mode prompt, including its system prompt template, teammate instructions, organization-variable substitutions, and any shared system-teammate prefix
• current organization and token-owner user context
• available organization variable names
• the teammate's accessible workspace skills and their descriptions
• guidance to activate a relevant skill before starting and to use `skill_search` or `skill_read` for supporting details

Hosted MCP has no workflow run or conversation behind the connection, so this prompt context has no chat history or contact. Tool execution still uses the organization, employee, and user scope resolved from the token.

The MCP server identifier and generated client configuration entry remain `alloy`.

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.

When `storage.get_temp_file_url` is approved for the teammate, Hosted MCP can use it without a workflow run. The resulting `/shared/files/link/{link_id}` URL is an opaque bearer-style link that expires ten minutes after it is minted. It is for immediate tool-to-tool handoff, not for sending to an end user.

• Treat PATs as bearer credentials.
• Delete a PAT 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 (widened by its

Storage workspace and system-teammate status), workflows, storage permissions, and MCP assignments.