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

# Setup Guide

> Connect Claude, ChatGPT, Cursor, VS Code, GitHub Copilot, Codex, Windsurf or any other MCP client to Echod by signing in.

Assistants connect by signing in to Echod - OAuth, with nothing to copy but the server URL. The first time your assistant connects, it opens Echod in your browser, where you sign in and approve it.

> [!TIP]
>
> The fastest way to connect is from the app: **Settings > MCP Server** shows the server URL and the exact steps or snippet for your assistant. This page explains the same setup in general terms.

## 1. Get the server URL

In Echod, open **Settings > MCP Server** and copy the server URL (it ends in `/mcp`). That is all your assistant needs - no token.

## 2. Add it to your assistant

| Client | How to connect |
| - | - |
| Claude Code | `claude mcp add echod --transport http <url>`, then run `/mcp` inside Claude Code, choose **echod** and sign in in the browser that opens. Add `--scope user` to use it in every project. |
| Claude (claude.ai, Claude Desktop, mobile) | **Settings > Connectors > Add custom connector**: name it echod, paste the server URL, choose **Connect** and sign in. The connector then works in claude.ai, Claude Desktop and the Claude mobile apps. |
| ChatGPT | **Settings > Apps and Connectors**, turn on developer mode under **Advanced settings**, create a connector with the server URL and choose **OAuth** for authentication, then sign in. |
| Cursor | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project. Cursor asks you to sign in the first time it connects. |
| VS Code (GitHub Copilot) | `.vscode/mcp.json` in your workspace, under a `servers` key instead of `mcpServers`. VS Code asks you to sign in when it starts the server. |
| GitHub Copilot CLI | `~/.copilot/mcp-config.json`, or run `/mcp add` inside Copilot CLI. |
| OpenAI Codex | `~/.codex/config.toml`, as `[mcp_servers.echod]`, then run `codex mcp login echod` to sign in. The app renders the TOML for you. |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` (uses `serverUrl` instead of `url`), then refresh the MCP servers. It asks you to sign in. |
| Other MCP clients | Add the server URL under your client's MCP configuration (usually `mcpServers`); check its documentation for where that file lives. |

A typical JSON entry contains only the address:

```json theme={null}
{
  "mcpServers": {
    "echod": {
      "type": "http",
      "url": "https://<your echod host>/mcp"
    }
  }
}
```

> [!WARNING]
>
> Do not add an `Authorization` header for an assistant that signs in - a configured header can stop the sign-in from working. Headers are only for [scripts and automation](#scripts-and-automation).

## 3. Approve it in your browser

When the assistant first connects, Echod opens a consent page that shows which app is asking and how far Echod could verify its identity. Approving gives the assistant read-only access to every project you can open; it cannot change anything. Approve only a request you just started yourself.

Approved assistants appear under **Connected apps** in **Settings > MCP Server**, with when each was connected and last used. You can disconnect one at any time; it loses access on its next request.

## 4. Try it

Restart your client if it reads configuration at startup, then ask:

> List my Echod projects

If your projects come back, you are connected.

## Scripts and automation

Assistants sign in, so access tokens are only for what has no browser to sign in with: scripts, CI and agents you build yourself.

1. In Echod, open **Settings > MCP Server** and create an access token under **For scripts and automation**. Optionally give it an expiry (30, 60 or 90 days, or none).
2. Copy the token (it starts with `echod_pat_`). It is shown once; if you lose it, revoke it and create a new one.
3. Send it as a bearer header to the server URL: `Authorization: Bearer echod_pat_...`.

The token acts as you: the script sees the projects you can open, read-only. Create one per script, so you can revoke it without breaking the others. The same route works for an MCP client that cannot sign in: configure the server URL with that `Authorization` header.

## Troubleshooting

* **The browser never opens to sign in**: most clients read MCP configuration at startup; restart the client after adding the server. If the client cannot sign in to MCP servers at all, use an access token as described above.
* **"This request has expired" on the consent page**: a connection request lasts ten minutes and works once. Go back to your assistant and connect again.
* **The assistant lost access**: it was disconnected under **Connected apps**, or its sign-in lapsed. Connect and approve it again.
* **401 or "unauthorized" with a token**: the token is missing, mistyped, expired or revoked. Create a new one in **Settings > MCP Server**.
* **429 or "rate limited"**: the response includes a retry delay; your assistant retries after it. Sustained bursts across many parallel calls are the usual cause.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.