Quickstart

MCP Server is an experimental feature

MCP Server may change or be removed without notice. It is off by default: enable it per site under Configurations > Experimental features before following the steps on this page.

Goal: connect your coding agent to your site’s MCP server and make one tool call that returns real content from the site.

What you’ll have when you’re done

• The MCP Server experimental feature enabled on your site.
• Your coding agent connected to the Source CMS MCP Server over streamable HTTP (MCP’s plain-HTTP transport; nothing extra to install or run), authorized via OAuth.
• One successful tool call that returns real site content.

Prerequisites

• An Acquia account with access to a Source CMS site (don’t have one?)
• One of these agent harnesses installed: Claude Code, Claude Desktop, Cursor, VS Code with Copilot, GitHub Copilot in your IDE, OpenCode, or Codex
• A project directory to run the agent in: most of them store the server config per project

Steps

1. Enable the MCP Server on your site

   In your site’s admin UI, in the left sidebar click Configurations, then Experimental features. Locate the MCP Server section, toggle Enable MCP Server to ON, and click Save configuration.

2. Copy the connection URL

   Still on the Experimental features page, click Configure to open the MCP server connection details. Copy the URL shown under MCP client configuration: it is your site URL with /mcp appended ({DRUPAL_SITE_URL}/mcp). You don’t need to change any other settings on this page.

3. Add the server to your agent

   Replace <URL> with the MCP URL you copied in the previous step.

   Claude Code

   In your project directory, run:

   claude mcp add acquia-source-mcp <URL> \
     --transport http --scope project

   The command confirms:

   Added HTTP MCP server acquia-source-mcp with URL:
   <your MCP URL> to project config
   File modified: /path/to/project/.mcp.json

   --scope project stores the server in a .mcp.json file at the project root, so teammates who open the same project get the same server.

   Claude Desktop

   In Claude Desktop, go to Customize > Connectors, click +, then Add custom connector. Paste <URL> as the connector’s remote MCP server URL and click Add. On a Team or Enterprise plan, an Owner adds the connector first, under Organization settings > Connectors.

   Custom connectors reach the server from Anthropic’s cloud, not from your machine, so the site must be reachable over the public internet.

   Cursor

   Add the server to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

   {
     "mcpServers": {
       "acquia-source-mcp": {
         "url": "<URL>"
       }
     }
   }

   VS Code

   Add the server to .vscode/mcp.json in your project (or run MCP: Add Server from the Command Palette):

   {
     "servers": {
       "acquia-source-mcp": {
         "type": "http",
         "url": "<URL>"
       }
     }
   }

   Committing the file shares the server with everyone who opens the project.

   GitHub Copilot

   Copilot Chat in VS Code reads MCP servers from the repository’s .vscode/mcp.json; add the file shown under VS Code. On a Copilot Business or Enterprise plan, the MCP servers in Copilot policy must be enabled for your organization. JetBrains, Visual Studio, Eclipse, and Xcode carry their own MCP configuration files: see Extending Copilot Chat with MCP.

   OpenCode

   Add the server to opencode.json at your project root:

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "acquia-source-mcp": {
         "type": "remote",
         "url": "<URL>"
       }
     }
   }

   Codex

   In your terminal, run:

   codex mcp add acquia-source-mcp --url <URL>

   Codex stores the server in ~/.codex/config.toml, so it follows you across projects.

4. Authenticate

   Your browser opens the site’s OAuth authorization flow; sign in with your site account if prompted, then click Allow.

   Claude Code

   Open Claude Code (claude), then type /mcp to manage MCP servers. Select acquia-source-mcp and choose Authenticate. After the browser flow, the server’s status changes to connected.

   Claude Desktop

   On Customize > Connectors, click Connect on the connector and finish the browser flow.

   Cursor

   Reload Cursor in the project. It picks up the new server and walks you through the browser OAuth flow.

   VS Code

   When the server first starts, VS Code asks you to confirm that you trust it, then opens a browser window to complete the authorization.

   GitHub Copilot

   In VS Code, confirm the trust prompt and complete the browser authorization. MCP: List Servers in the Command Palette shows the configured server.

   OpenCode

   Start OpenCode in the project. It prompts for authentication on the server’s first use; to trigger the flow yourself, run opencode mcp auth acquia-source-mcp.

   Codex

   Run codex mcp login acquia-source-mcp and complete the browser flow. codex mcp list shows the server’s auth status.

5. Make one call that returns real site content

   Ask your agent to read from your site:

   > Use acquia-source-mcp to list the most recent
   > articles on this site.

   The agent asks permission to use the list_entities tool. Approve it. The response comes from your site’s actual content; in Claude Code the exchange looks like this:

   ⏺ acquia-source-mcp - list_entities (MCP)
   
   ⏺ Your site has 3 published articles:
     1. "Spring launch announcement"
     2. "How we redesigned onboarding"
     3. "Meet the new dashboard"

   The titles you see are your site’s real entries; the agent read them through the MCP server, not from training data.

What just happened

Your site now runs an MCP server: a standard interface AI agents use to discover read-only resources and call tools that create or update data. Your agent connected to it over streamable HTTP, and the OAuth flow you approved in the browser is what authorizes every subsequent request. The list_entities call was a real round trip: your agent → your site’s MCP server → your site’s content, back as structured data the agent can act on.

When something goes wrong

The failure states below are shown with Claude Code’s commands; the same causes apply in every client, each surfacing them through its own MCP status view.

✗ Failed to connect next to acquia-source-mcp in claude mcp list

the site isn’t serving MCP at that URL. Confirm Enable MCP Server is toggled ON under Configurations > Experimental features and saved, then re-copy the URL from the Configure panel; the feature is per-site, so check you enabled it on the same site whose URL you pasted.

No MCP servers configured when you type /mcp

you added the server with --scope project but launched Claude Code from a different directory. Run claude from the directory containing .mcp.json, or re-run the claude mcp add command from step 3 in the directory you actually work in.

The server is in .mcp.json but never appears in /mcp

Claude Code asks for approval the first time it sees a project-scoped server, and remembers a rejection. Run claude mcp reset-project-choices and restart Claude Code to get the approval prompt again.

Tool calls fail with 401 Unauthorized, or the server status shows it needs authentication

the OAuth authorization was never completed or has expired. In /mcp, select acquia-source-mcp, choose Authenticate, and complete the browser flow through the Allow button. More OAuth failure cases are in the auth guide’s troubleshooting.

Next steps

• MCP server integration guide: resource URIs, the full tool catalog, MCP Inspector for debugging, and known limits.
• MCP server reference: the connection spec and every tool and resource.
• Write content through the API: what the agent’s create_node calls do at the API level.