Start for free

Claude MCP integration

What is Model Context Protocol (MCP)?

MCP is a standardized protocol that allows AI assistants like Claude to securely access structured data from other applications. When you integrate Alloy with Claude Desktop via MCP, Claude can use Alloy session links to retrieve the context behind a prototype or dev session.

With the Alloy MCP integration, Claude can:

  1. Resolve Alloy session links: Paste an Alloy session URL and Claude can identify the matching session in your workspace.
  2. Read chat history: Claude can retrieve the messages from an Alloy session so it understands the decisions and prompts that led to the current result.
  3. Inspect code context: Claude can list session files and retrieve file content, including before-and-after diffs for dev sessions.

Setting up Claude Desktop with OAuth

Claude Desktop connects to Alloy over OAuth. You do not need to create an MCP key or paste secrets into your Claude config.

1. Configure Claude Desktop for OAuth

  1. Open Claude Desktop on your computer.
  2. Click Claude in your top menu bar, then click Settings.
  3. Select Developers from the sidebar.
  4. Click Edit config.
  5. Add Alloy as a remote MCP server:
{
  "mcpServers": {
    "alloy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.alloy.app/mcp"
      ]
    }
  }
}
  1. Save the config and restart Claude Desktop.

2. Authorize Alloy

After Claude Desktop restarts, it will start the Alloy MCP server entry. The first time Claude needs Alloy context, mcp-remote opens an Alloy authorization page in your browser.

  1. Sign in to Alloy if prompted.
  2. Authorize Claude Desktop to access your Alloy workspace.
  3. Return to Claude Desktop and continue your conversation.

Once authorized, Claude will have secure access to Alloy session context for your workspace.

Claude Desktop currently reaches remote OAuth MCP servers through mcp-remote. Alloy supports dynamic client registration for this compatibility path, so the simple config above is enough. You should not need a fixed callback port, an MCP key header, or a manually configured client secret.

Setting up Claude Desktop with an MCP key

You can also connect Claude Desktop with an Alloy MCP key. This is useful when you want to manage access with a workspace-scoped key instead of using browser-based OAuth.

1. Generate an MCP key in Alloy

  1. Navigate to your workspace settings in Alloy.
  2. Select MCP from the sidebar.
  3. Click Create key.
  4. Copy the generated MCP key.

MCP keys are workspace-scoped. Claude can only access sessions that belong to the workspace associated with the key.

2. Configure Claude Desktop with the MCP key

  1. Open Claude Desktop on your computer.
  2. Click Claude in your top menu bar, then click Settings.
  3. Select Developers from the sidebar.
  4. Click Edit config.
  5. Paste the following config:
{
  "mcpServers": {
    "alloy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.alloy.app/mcp",
        "--header",
        "X-MCP-API-Key: <YOUR API KEY HERE>"
      ]
    }
  }
}
  1. Replace <YOUR API KEY HERE> with the MCP key you generated in Alloy.
  2. Save the config and restart Claude Desktop.

Once connected, Claude will have secure access to Alloy session context for your workspace.

Using Claude Desktop with Alloy

With the integration set up, you can paste Alloy links into Claude and ask questions about the session. Alloy session URLs can be provided as full URLs, such as https://alloy.app/.../p/.../edit or https://alloy.app/.../p/dev/....

You can ask Claude questions like:

  • "Summarize the chat history for this Alloy session: https://alloy.app/.../p/.../edit"
  • "What files changed in this dev session, and what are the important diffs? https://alloy.app/.../p/dev/..."
  • "Use the code context from this Alloy session to explain how the prototype works."
  • "Pull the chat messages from this Alloy session and turn the decisions into implementation notes."

Available Alloy MCP context

The Alloy MCP server is centered around Alloy sessions. Depending on the session type, Claude can access:

  • Session metadata, including the session title, type, timestamps, status, and related workspace context.
  • Chat messages from a specific session, ordered from oldest to newest.
  • File lists for prototype and dev sessions.
  • Prototype session file content.
  • Dev session before-and-after file diffs for files changed during the session.

This lets Claude answer questions using the same context your team sees in Alloy without requiring you to manually copy messages, files, or diffs into the conversation.

Troubleshooting

If Claude cannot access Alloy session context, check the following:

  • For OAuth, complete the browser authorization flow that opens after Claude Desktop starts the Alloy MCP server.
  • For MCP keys, confirm the MCP key is copied correctly and has not been deleted from Alloy.
  • Confirm the Alloy session belongs to the workspace you authorized or the workspace where the MCP key was created.
  • Restart Claude Desktop after changing the MCP config.
  • Make sure the MCP server URL is https://mcp.alloy.app/mcp.
  • If Claude keeps using an old authorization attempt, remove the cached mcp-remote auth entry for Alloy and restart Claude Desktop.