Start for free

MCP

Alloy's MCP server lets AI assistants access the context behind your Alloy sessions: design context, chat history, generated files, and code diffs where available.

Use MCP when you want an assistant to understand what happened in Alloy without copying messages, screenshots, files, or implementation notes by hand.

Server details

The Alloy MCP server is hosted at:

https://mcp.alloy.app/mcp

Alloy supports remote Streamable HTTP MCP with OAuth. For clients that do not support remote HTTP directly, use mcp-remote as a local bridge.

Claude

Claude can connect to Alloy with a custom connector.

  1. Open Claude connectors.
  2. Confirm the connector name is Alloy.
  3. Confirm the connector URL is:
https://mcp.alloy.app/mcp
  1. Add the connector.
  2. Click Connect and authorize Alloy when prompted.

If you are on a Claude Team or Enterprise plan, an Owner or Primary Owner may need to add the custom connector for the organization first. After that, each member can connect Alloy from Claude's connector settings.

Codex

Codex shares MCP configuration across the app, CLI, and IDE extension.

Run this command in Terminal:

codex mcp add alloy --url https://mcp.alloy.app/mcp

Then authenticate:

codex mcp login alloy

If you already have an alloy MCP server configured and want to recreate it, remove it first:

codex mcp remove alloy
codex mcp add alloy --url https://mcp.alloy.app/mcp
codex mcp login alloy

Claude Code

Claude Code supports remote HTTP MCP servers.

Run this command in Terminal:

claude mcp add --transport http alloy https://mcp.alloy.app/mcp

Then open Claude Code and run:

/mcp

Use the MCP menu to authenticate Alloy and enable the server for the current session.

Visual Studio Code

Visual Studio Code can use remote MCP servers from an mcp.json file.

  1. Open the Command Palette with Cmd+Shift+P.
  2. Run MCP: Open User Configuration to configure Alloy globally, or create .vscode/mcp.json in a workspace to share the config with that project.
  3. Add this configuration:
{
  "servers": {
    "alloy": {
      "type": "http",
      "url": "https://mcp.alloy.app/mcp"
    }
  }
}
  1. Run MCP: List Servers from the Command Palette.
  2. Select alloy, then start the server and complete the Alloy authorization flow.

Windsurf

Windsurf Cascade can connect to MCP servers from ~/.codeium/windsurf/mcp_config.json.

  1. Open Windsurf settings with Cmd+,.
  2. Go to Cascade > MCP Servers.
  3. Add a custom server, or edit ~/.codeium/windsurf/mcp_config.json directly.
  4. Add this configuration:
{
  "mcpServers": {
    "alloy": {
      "serverUrl": "https://mcp.alloy.app/mcp"
    }
  }
}
  1. Save the file, refresh MCP servers in Cascade, and authorize Alloy when prompted.

If your Windsurf version does not start remote HTTP MCP servers from serverUrl, use the local bridge configuration instead:

{
  "mcpServers": {
    "alloy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.alloy.app/mcp"]
    }
  }
}

Other MCP clients

For MCP clients that support remote Streamable HTTP servers, use:

Name: Alloy
URL: https://mcp.alloy.app/mcp
Transport: Streamable HTTP
Authentication: OAuth

For MCP clients that only support local stdio servers, use mcp-remote:

{
  "mcpServers": {
    "alloy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.alloy.app/mcp"]
    }
  }
}

Workspace admins can also create an MCP key from Alloy settings. Use this only when your client cannot complete browser-based OAuth and supports custom request headers:

{
  "mcpServers": {
    "alloy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.alloy.app/mcp",
        "--header",
        "X-MCP-API-Key: <YOUR MCP KEY>"
      ]
    }
  }
}

What the assistant can access

Depending on the session type, Alloy MCP can expose:

  • Session metadata, including title, type, timestamps, status, and workspace context.
  • Chat messages from a session.
  • File lists for sessions.
  • Prototype session file content.
  • Before-and-after file diffs where available.

This gives your assistant the same working context your team sees in Alloy.

Troubleshooting

If your assistant cannot access Alloy context:

  • Make sure the server URL is exactly https://mcp.alloy.app/mcp.
  • Complete the browser authorization flow for the same Alloy workspace that owns the session.
  • Confirm the session URL belongs to the workspace you authorized.
  • Restart the MCP server from your client after changing configuration.
  • If you use mcp-remote, make sure Node.js and npx are available in the environment where the client starts MCP servers.
  • If you use an MCP key, confirm the key is active and copied without extra spaces.