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 via MCP, Claude can use Alloy session links to retrieve the context behind a 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 where available.

Setting up Claude with OAuth

Claude connects to Alloy over OAuth. You do not need to create an MCP key or edit Claude's local config file.

1. Add Alloy as a custom connector

  1. Open Claude or Claude Desktop.
  2. Open Settings and navigate to Customize > Connectors.
  3. Click the + button next to Connectors, then select Add custom connector.
  4. Enter Alloy as the connector name.
  5. Enter the MCP server URL:
https://mcp.alloy.app/mcp
  1. Leave the advanced OAuth client ID and secret fields blank.
  2. Click Add.

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 from Organization settings > Connectors. After that, each member can connect it from Customize > Connectors.

2. Authorize Alloy

  1. Find the Alloy connector in Claude's connector settings.
  2. Click Connect.
  3. Sign in to Alloy if prompted.
  4. Authorize Claude to access your Alloy workspace.
  5. Return to Claude and start a new conversation.

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

Setting up Claude with an MCP key

You can also connect Claude 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 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 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/.... In a conversation, use the + menu, open Connectors, and make sure Alloy is enabled for that chat.

You can ask Claude questions like:

  • "Summarize the chat history for this Alloy session: https://alloy.app/.../p/.../edit"
  • "What files changed in this session, and what are the important diffs? https://alloy.app/.../p/..."
  • "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 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:

  • Complete the browser authorization flow from Claude's connector settings.
  • 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.
  • In the current conversation, make sure Alloy is enabled from the + menu under Connectors.
  • Make sure the MCP server URL is https://mcp.alloy.app/mcp.
  • If authentication fails, disconnect and reconnect the Alloy connector from Customize > Connectors.