> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sidecars.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent

> Add the Sidecars MCP server to Claude Code, Claude.ai, Cursor, VS Code, Codex, ChatGPT, Windsurf, Zed or any other host: one URL, OAuth sign-in, no API keys.

export const CopyToAgent = ({prompt}) => {
  const [copied, setCopied] = useState(false);
  const [focused, setFocused] = useState(false);
  useEffect(() => {
    if (!copied) return;
    const timer = setTimeout(() => setCopied(false), 4000);
    return () => clearTimeout(timer);
  }, [copied]);
  const copy = () => {
    if (!navigator?.clipboard) return;
    navigator.clipboard.writeText(prompt).then(() => setCopied(true), () => setCopied(false));
  };
  return <div className="not-prose my-6 rounded-2xl border border-zinc-950/10 p-5 dark:border-white/15">
      <h3 className="text-base font-semibold text-zinc-950 dark:text-white">
        Let your agent set up Sidecars
      </h3>
      <p className="mt-1 text-sm text-zinc-950/70 dark:text-white/70">
        Click below to copy the setup prompt, then paste it into your agent.
      </p>
      <div className="mt-4">
        <button aria-live="polite" className="inline-flex items-center rounded-lg bg-zinc-950 px-3 py-2 text-sm font-medium text-white transition-opacity hover:opacity-80 dark:bg-white dark:text-zinc-950" onBlur={() => setFocused(false)} onClick={copy} onFocus={event => setFocused(event.target.matches(":focus-visible"))} style={focused ? {
    outline: "2px solid rgb(113 113 122)",
    outlineOffset: "2px"
  } : undefined} type="button">
          {copied ? "Copied! Paste it into your agent." : "Copy to your agent"}
        </button>
      </div>
      <p className="mt-4 select-text rounded-xl bg-zinc-950/5 p-3 text-sm text-zinc-950/70 dark:bg-white/10 dark:text-white/70">
        {prompt}
      </p>
    </div>;
};

export const CopyServerUrl = ({url}) => {
  const [copied, setCopied] = useState(false);
  const [focused, setFocused] = useState(false);
  useEffect(() => {
    if (!copied) return;
    const timer = setTimeout(() => setCopied(false), 4000);
    return () => clearTimeout(timer);
  }, [copied]);
  const copy = () => {
    if (!navigator?.clipboard) return;
    navigator.clipboard.writeText(url).then(() => setCopied(true), () => setCopied(false));
  };
  return <div className="not-prose my-4">
      <button aria-live="polite" className="inline-flex items-center rounded-lg border border-zinc-950/10 px-3 py-2 text-sm font-medium text-zinc-950 transition-colors hover:bg-zinc-950/5 dark:border-white/15 dark:text-white dark:hover:bg-white/10" onBlur={() => setFocused(false)} onClick={copy} onFocus={event => setFocused(event.target.matches(":focus-visible"))} style={focused ? {
    outline: "2px solid rgb(113 113 122)",
    outlineOffset: "2px"
  } : undefined} type="button">
        {copied ? "Copied!" : "Copy server URL"}
      </button>
    </div>;
};

The Sidecars MCP server is a **remote, streamable-HTTP** MCP server. There is
one URL, no API key, and no secret to paste into a config file. Sign-in
happens through the standard MCP OAuth flow in your browser.

The fastest way in is to let the agent you already have do the setup.

<CopyToAgent prompt="Help me connect this agent to Sidecars. Add https://mcp.sidecars.ai/mcp as a Streamable HTTP MCP server named sidecars using this client's supported setup method. Preserve my existing MCP configuration. If you cannot configure the connection directly, walk me through the required settings. Guide me through sign-in, then verify the connection with an available read-only tool. If a restart or new session is required, explain that before claiming the connection is ready." />

The prompt works in any agent that manages its own MCP configuration. An
agent that cannot configure the connection itself will walk you through the
settings below instead.

## Manual setup

```text theme={null}
https://mcp.sidecars.ai/mcp
```

<CopyServerUrl url="https://mcp.sidecars.ai/mcp" />

<Note>
  The Developers page inside the app (sidebar → **Developers**, or
  [sidecars.ai/developers](https://sidecars.ai/developers)) shows the exact URL
  for your deployment. The commands below are the same ones that page
  generates, with the production URL filled in. The URL is for MCP clients;
  opening it in a browser shows an error.
</Note>

### Per-host setup

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http sidecars https://mcp.sidecars.ai/mcp
    ```

    Then run `/mcp` inside Claude Code, choose **sidecars** and pick **Login**.

    Or add it by hand to `.mcp.json` in your project (or `~/.claude.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "sidecars": { "type": "http", "url": "https://mcp.sidecars.ai/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Claude.ai / Desktop">
    Settings → **Connectors** → **Add custom connector** → paste the URL.
  </Tab>

  <Tab title="Cursor">
    Use the **Install in Cursor** button on the Developers page, or add to
    `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "sidecars": { "url": "https://mcp.sidecars.ai/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    ```bash theme={null}
    code --add-mcp '{"name":"sidecars","type":"http","url":"https://mcp.sidecars.ai/mcp"}'
    ```

    Or in `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "sidecars": { "type": "http", "url": "https://mcp.sidecars.ai/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add sidecars --url https://mcp.sidecars.ai/mcp
    codex mcp login sidecars
    ```
  </Tab>

  <Tab title="ChatGPT">
    Settings → **Apps & Connectors** → **Advanced** → enable **Developer mode**
    → **Create** → paste the URL.
  </Tab>

  <Tab title="Windsurf">
    In `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "sidecars": { "serverUrl": "https://mcp.sidecars.ai/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Zed">
    Zed connects through `mcp-remote`. In Zed's `settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "sidecars": {
          "source": "custom",
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.sidecars.ai/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Any other host

* **Cross-agent installer:** `npx add-mcp https://mcp.sidecars.ai/mcp`
* **Hosts that cannot speak streamable HTTP:** `npx -y mcp-remote https://mcp.sidecars.ai/mcp`

## What happens on first use

<Steps>
  <Step title="Discovery is public">
    `initialize`, `ping`, `tools/list` and `resources/list` answer without a
    token, so a host can show the tool catalogue before you sign in.
  </Step>

  <Step title="The first tool call is challenged">
    The first `tools/call` returns `401` with a `WWW-Authenticate` challenge.
    The host reads the server's protected-resource metadata, discovers the
    authorization server, and opens a browser tab.
  </Step>

  <Step title="Sign in and pick a workspace">
    You sign in (or sign up) and land on the consent screen, where you choose
    the workspace this connection acts in. A brand-new account can create its
    workspace right there.
  </Step>

  <Step title="The call is retried with a token">
    The host stores the access token and retries. Tokens expire after
    24 hours; the host refreshes or re-prompts as needed.
  </Step>
</Steps>

<Warning>
  Scopes are granted incrementally. A first connect asks only for identity and
  `knowledge:read`. The first time an agent calls a document, page, comment or
  export tool, the server answers `403 insufficient_scope` naming the missing
  scope and the host re-runs consent for it. See
  [Authentication and access](/authentication).
</Warning>

## Advanced setup

<Accordion title="Transport details">
  | Property          | Value                                                                                                                                                                                                                                             |
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Transport         | Streamable HTTP, no sessions. Clients on the current protocol get `application/json` responses. Clients on the 2025-era shim get one SSE-framed event (`Content-Type: text/event-stream`) carrying the JSON-RPC message, with no stream kept open |
  | `Accept` header   | Send `application/json, text/event-stream`. The legacy shim answers `406` to anything less; the current protocol accepts either                                                                                                                   |
  | Methods           | `POST` for JSON-RPC; `OPTIONS` for CORS preflight                                                                                                                                                                                                 |
  | Protocol versions | Current spec plus the 2025-03-26 and 2025-06-18 era shim, so older clients are served                                                                                                                                                             |
  | Batching          | Not supported (removed from the protocol in 2025-06-18)                                                                                                                                                                                           |
  | Discovery         | `/.well-known/oauth-protected-resource/mcp` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414, proxied for legacy clients)                                                                                                       |
  | Server name       | `sidecars`                                                                                                                                                                                                                                        |
</Accordion>