# Quickstart

<ExperimentalFeatureAside feature="MCP Server" />

**Goal:** connect your coding agent to your [site](/start-here/glossary/#site)'s [MCP server](/start-here/glossary/#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?](/start-here/choose-your-backend/))
- One of these agent harnesses installed: [Claude Code](https://code.claude.com/docs/en/overview), [Claude Desktop](https://claude.com/download), [Cursor](https://cursor.com), [VS Code](https://code.visualstudio.com/) with Copilot, [GitHub Copilot](https://docs.github.com/en/copilot) in your IDE, [OpenCode](https://opencode.ai), or [Codex](https://developers.openai.com/codex)
- A project directory to run the agent in: most of them store the server config per project

## Steps

<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.

   <Tabs syncKey="agent">
     <TabItem label="Claude Code">
       In your project directory, run:

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

       The command confirms:

       ```text
       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.
     </TabItem>
     <TabItem label="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.
     </TabItem>
     <TabItem label="Cursor">
       Add the server to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):

       ```json
       {
         "mcpServers": {
           "acquia-source-mcp": {
             "url": "<URL>"
           }
         }
       }
       ```
     </TabItem>
     <TabItem label="VS Code">
       Add the server to `.vscode/mcp.json` in your project (or run `MCP: Add Server` from the Command Palette):

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

       Committing the file shares the server with everyone who opens the project.
     </TabItem>
     <TabItem label="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](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp).
     </TabItem>
     <TabItem label="OpenCode">
       Add the server to `opencode.json` at your project root:

       ```json
       {
         "$schema": "https://opencode.ai/config.json",
         "mcp": {
           "acquia-source-mcp": {
             "type": "remote",
             "url": "<URL>"
           }
         }
       }
       ```
     </TabItem>
     <TabItem label="Codex">
       In your terminal, run:

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

       Codex stores the server in `~/.codex/config.toml`, so it follows you across projects.
     </TabItem>
   </Tabs>

4. ### Authenticate

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

   <Tabs syncKey="agent">
     <TabItem label="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.
     </TabItem>
     <TabItem label="Claude Desktop">
       On `Customize > Connectors`, click `Connect` on the connector and finish the browser flow.
     </TabItem>
     <TabItem label="Cursor">
       Reload Cursor in the project. It picks up the new server and walks you through the browser OAuth flow.
     </TabItem>
     <TabItem label="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.
     </TabItem>
     <TabItem label="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.
     </TabItem>
     <TabItem label="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`.
     </TabItem>
     <TabItem label="Codex">
       Run `codex mcp login acquia-source-mcp` and complete the browser flow. `codex mcp list` shows the server's auth status.
     </TabItem>
   </Tabs>

5. ### Make one call that returns real site content

   Ask your agent to read from your site:

   ```text
   > 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:

   ```text
   ⏺ 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.

</Steps>

## 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](/source-cms/authenticate/guide/#when-something-goes-wrong).

## Next steps

- [MCP server integration guide](/source-cms/ai-agents/guide/): resource URIs, the full tool catalog, MCP Inspector for debugging, and known limits.
- [MCP server reference](/source-cms/reference/mcp-server/): the connection spec and every tool and resource.
- [Write content through the API](/source-cms/content-api/writing-content/): what the agent's `create_node` calls do at the API level.