# Install the Ideally MCP server

You are an AI agent. The user asked you to connect the Ideally MCP server to the client you are running in. Follow these steps in order. Do the work yourself; only stop to ask the user where a step says so.

- Server name: `ideally`
- URL: `https://mcp.goideally.com/mcp`
- Transport: streamable HTTP
- Authentication: OAuth. The client signs the user in through their browser. Never ask the user for an API key.

## 1. Work out which client you are in

Use what you know about yourself first, then your environment variables and the config files you can see:

| Client | Signs |
| --- | --- |
| Claude Code | you are Claude Code; `CLAUDECODE=1`; the `claude` CLI is on PATH |
| Codex CLI | you are Codex; `CODEX_HOME` or `~/.codex/config.toml`; the `codex` CLI |
| Cursor | you are running in Cursor; `CURSOR_TRACE_ID`; `~/.cursor/` |
| VS Code (GitHub Copilot) | you are GitHub Copilot; `TERM_PROGRAM=vscode` with no Cursor or Windsurf signs; the `code` CLI |
| Gemini CLI | you are Gemini CLI; `GEMINI_CLI=1`; `~/.gemini/settings.json` |
| Windsurf | you are Cascade in Windsurf; `~/.codeium/windsurf/` |
| Claude (web or desktop) | you are Claude with no shell and no file access |
| ChatGPT | you are ChatGPT |
| Microsoft Copilot Studio | you are Microsoft Copilot, Microsoft 365 Copilot or a Copilot Studio agent |

If you still cannot tell, ask the user one question: "Which app are you using: Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI, Windsurf, Claude (web or desktop), ChatGPT or Microsoft Copilot?"

## 2. Install for that client

Follow the section for your client below.

- **Merge, never overwrite.** When you edit a config file, read it first, add or update only the `ideally` entry and keep every other server and setting exactly as it was. Create the file only if it does not exist.
- **Never duplicate.** If a `ideally` entry already exists, update it in place.
- **Claude (web or desktop), ChatGPT and Microsoft Copilot Studio:** you cannot change these yourself. Give the user the steps from their section, with the URL ready to paste, and stop there.

### Claude Code

```sh
claude mcp add --scope user --transport http ideally https://mcp.goideally.com/mcp
```

If `claude mcp get ideally` already lists the server, run `claude mcp remove --scope user ideally` first, then add it again. Then run `/mcp` inside Claude Code, pick `ideally` and choose **Authenticate**.

### Codex CLI

```sh
codex mcp add ideally --url https://mcp.goideally.com/mcp
codex mcp login ideally
```

Running `add` again with the same name replaces the entry. `login` opens the browser.

### Cursor

Edit `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (this project only) and add `ideally` under `mcpServers`:

```json
{
  "mcpServers": {
    "ideally": {
      "url": "https://mcp.goideally.com/mcp"
    }
  }
}
```

Then open **Cursor Settings → MCP** and click **Connect** next to `ideally`.

### VS Code (GitHub Copilot)

```sh
code --add-mcp '{"name":"ideally","type":"http","url":"https://mcp.goideally.com/mcp"}'
```

Or add it to `.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "ideally": {
      "type": "http",
      "url": "https://mcp.goideally.com/mcp"
    }
  }
}
```

VS Code asks to sign in the first time Copilot agent mode uses the server. Choose **Allow**.

### Gemini CLI

Edit `~/.gemini/settings.json` and add `ideally` under `mcpServers`:

```json
{
  "mcpServers": {
    "ideally": {
      "httpUrl": "https://mcp.goideally.com/mcp",
      "oauth": { "clientId": "gemini-cli" }
    }
  }
}
```

Then run `/mcp auth ideally` inside Gemini CLI. The client id signs Gemini CLI in as itself; without it, the sign-in page warns that Ideally hasn't verified the app.

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json` and add `ideally` under `mcpServers`:

```json
{
  "mcpServers": {
    "ideally": {
      "serverUrl": "https://mcp.goideally.com/mcp"
    }
  }
}
```

Then open **Windsurf Settings → Cascade → MCP servers**, refresh, and sign in when asked.

### Claude (web and desktop)

1. Open **Settings → Connectors** and click **Add custom connector**.
2. Name it `ideally` and paste the URL: `https://mcp.goideally.com/mcp`
3. Click **Add**, then **Connect**, and sign in.

### ChatGPT

1. Open **Settings → Plugins** (or the Plugins Directory) and search for **Ideally**.
2. Click **Connect**, then sign in with your Ideally account.

On a ChatGPT Business, Enterprise or Edu workspace, an admin may need to enable Ideally first. If **Connect** is greyed out or says **Disabled by admin**, ask your workspace admin.

The listed Ideally app connects to `https://mcp.goideally.com/mcp`. To connect a different server, such as a test stage, add it as a custom app instead:

1. Open **Settings → Apps → Advanced settings** and turn on **Developer mode**.
2. Click **Create app**. Name it `ideally`, paste the URL `https://mcp.goideally.com/mcp` and choose **OAuth** authentication.
3. Click **Create**, then sign in.

### Microsoft Copilot Studio

Add Ideally as a tool on a Copilot Studio agent. Publish that agent to Microsoft 365 Copilot or Teams to use it there.

1. Open your agent, go to **Tools** and click **Add a tool → New tool → Model Context Protocol**.
2. Name it `ideally`, add a short description (for example "Ideally studies, results and Canvas") and paste the URL: `https://mcp.goideally.com/mcp`
3. Under **Authentication** choose **OAuth 2.0**, then **Dynamic discovery**, and click **Create**.
4. Click **Next**. In **Add tool**, choose **Create a new connection** and sign in with your Ideally account.
5. Click **Add to agent**.

If **Model Context Protocol** is missing from **New tool**, MCP tools are not enabled for your Copilot Studio environment yet. Ask your Power Platform admin.


## 3. Sign in

Start the sign-in as your client's section says. Tell the user: "A browser window will open. Sign in with your Ideally account and pick the account to connect." Wait for them to finish.

Only for a headless or CI setup with no browser, the server also accepts an Ideally API key in an `X-API-Key` header. Never suggest this for an interactive setup.

## 4. Verify

Call the `whoami` tool, then `list_teams`. Show the user which account they are signed in as and which teams they can see.

## 5. If something goes wrong

| What you see | What to do |
| --- | --- |
| The `ideally` tools do not appear | The client may need a restart to pick up new config. Ask the user to restart it (or reload the window), then verify again. |
| Sign-in did not finish, or a 401 / "unauthorized" | Start the sign-in again. If the browser did not open, give the user the URL your client printed. |
| The only Ideally tool is `mcp_access_unavailable` | Call it and pass its message on. The account does not have MCP access yet. Tell the user to contact their Ideally account manager. Do not retry. |
| A 403 / "forbidden" from a tool | The signed-in user has no access to that data. Ask whether they picked the right account when signing in. |
| Anything else | Tell the user exactly what failed and what you tried. Do not guess. |

## 6. Report back

Tell the user:

- What you changed: the file you edited (full path) or the command you ran.
- That the `ideally` server is connected, and the account and teams from step 4.
- Two things to try:
  - "List my recent Ideally studies."
  - "Summarise the results of my latest study."