# Connect Attune to your AI assistant

Attune runs AI-led surveys and interviews by voice or chat. Its
[Model Context Protocol](https://modelcontextprotocol.io) server lets the assistant you already use
build, launch, and edit a study, read your organization's business context, and analyze completed
responses, all without leaving that assistant.

The server is remote and hosted by Attune. There is nothing to install and no API key to manage:
you point your client at one URL and sign in with your Attune account.

```text
https://mcp.tryattune.ai/mcp
```

**What you need**

An active Attune workspace (sign up at [tryattune.ai](https://tryattune.ai)) and editor or
administrator permissions in your Attune organization. Ask your administrator whether MCP is
enabled for your organization.

## Connect your client

Every client below talks to the same endpoint over streamable HTTP and authenticates with OAuth.
The first tool call opens Attune's sign-in page at `login.tryattune.ai` in your browser. Sign in
with Google, or with your email address and password, using your work email. Then approve the
requested scopes once and the connection stays active.

In ChatGPT, Codex, and Claude, the [Attune plugin](/mcp/plugin/) sets this up for you in one step:
the plugin ships the server configuration plus Attune's research skills.

### ChatGPT

Install [the Attune plugin](/mcp/plugin/#chatgpt) from ChatGPT's plugin directory. It connects this
server for you, so there is no connector to add by hand.

### Claude (web and desktop)

1. Open **Settings → Connectors → Add custom connector**.

2. Name the connector `Attune` and paste the server URL:

   ```text
   https://mcp.tryattune.ai/mcp
   ```

3. Click **Connect** and complete the Attune login. Attune's tools appear in the tool menu of any
   new chat.

### Claude Code

```bash
claude mcp add --transport http attune https://mcp.tryattune.ai/mcp
```

Then run `/mcp` and choose **attune** to complete the login.

### Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "attune": {
      "url": "https://mcp.tryattune.ai/mcp"
    }
  }
}
```

### VS Code

Add the server to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "attune": {
      "type": "http",
      "url": "https://mcp.tryattune.ai/mcp"
    }
  }
}
```

### Windsurf

Add the server to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "attune": {
      "serverUrl": "https://mcp.tryattune.ai/mcp"
    }
  }
}
```

### Gemini CLI

Add the server to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "attune": {
      "httpUrl": "https://mcp.tryattune.ai/mcp"
    }
  }
}
```

### Codex

Install [the Attune plugin](/mcp/plugin/#codex) from the Codex plugin directory, which also brings
Attune's skills. To connect only the server, or to use the Codex IDE extension, add it to
`~/.codex/config.toml`:

```toml
[mcp_servers.attune]
url = "https://mcp.tryattune.ai/mcp"
```

### Any other MCP client

Register a remote server with transport **HTTP** (streamable HTTP), URL
`https://mcp.tryattune.ai/mcp`, and OAuth authorization. Attune publishes
[RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata at
`https://mcp.tryattune.ai/.well-known/oauth-protected-resource`, so clients that support OAuth
discovery need no further configuration. Attune does not accept static API keys.

## What you are authorizing

The login screen lists the scopes your client requested. Attune supports:

| Scope | What it allows |
|---|---|
| `openid` | Confirms who you are |
| `email` | Returns your email address, so your organization can restrict access by domain |
| `guides:read` | Read interview guides and your organization's business context |
| `guides:write` | Create, edit, and publish interview guides, get participant interview links, and update business context |
| `responses:read` | Read completed interview responses |
| `offline_access` | Keep the connection alive without signing in again |

Every tool call is scoped to your Attune organization, and a missing scope stops the call before
it runs.

## Try it

Ask your assistant:

- *"Survey my customers about the changes to our brand messaging."*
- *"Help me build an interview about churn."* — Attune confirms your business context, asks a few
  clarifying questions, and creates a draft guide you can open in the studio.
- *"Create a 10-minute guide to understand onboarding friction for SMB customers."*
- *"Summarize what participants said about pricing in my latest study."*

## Tool catalog

| Tool | Scope | What it does |
|---|---|---|
| `whoami` | `guides:read` | Returns your user ID and email, every organization you belong to with your role in it, plus your department and level |
| `suggest_interview_objectives` | `guides:read` | Suggests research objectives tailored to your company and role |
| `get_business_context` | `guides:read` | Reads your organization's stored research context |
| `update_business_context` | `guides:write` | Updates that context for the whole organization |
| `list_interview_guides` | `guides:read` | Lists guides in your organization |
| `get_interview_guide` | `guides:read` | Reads one guide in full |
| `create_interview_guide` | `guides:write` | Creates a draft guide from its `objective` argument, which can also appear in the web editor's Refine panel |
| `update_guide_settings` | `guides:write` | Changes one guide-level setting per call — title, length, interviewer, intro, conclusion, branding, or how participants respond (voice, chat, or both) |
| `edit_segments` | `guides:write` | Adds, updates, or reorders a guide's segments |
| `edit_questions` | `guides:write` | Adds, updates, or reorders the required questions of a structured segment |
| `edit_sample_questions` | `guides:write` | Adds, updates, or reorders the sample questions that steer a conversational segment |
| `remove_from_guide` | `guides:write` | Permanently removes one segment, question, or sample question |
| `apply_flow` | `guides:write` | Atomically rebuilds a guide's segment order, sections, routing, and classification or multiple-choice conversions |
| `publish_guide` | `guides:write` | Publishes a guide so interviews can start from it |
| `share_guide` | `guides:write` | Returns a new participant interview link for a published guide, to give to participants |
| `list_responses`, `get_response` | `responses:read` | Reads completed interview responses |
| `get_answers` | `responses:read` | Reads answers across responses, for one question or one segment |

If you belong to more than one organization, a call that names a guide or response uses that
guide's or response's organization. Other calls take an `organizationId` argument to choose the
organization; `whoami` lists yours.

Guide edits accept an `expectedRev` argument. Pass the revision you last read and Attune rejects
the call if someone edited the guide in the studio meanwhile, rather than overwriting their work.
`edit_segments` action `add` can create a classification segment with its complete classification
configuration. Action `update` can replace that configuration; include every category you want to
retain. To convert a structured or conversational segment, specify `type: "classification"` along
with the classification configuration.
`get_interview_guide` returns classification settings and stable category IDs for subsequent edits.
Use `apply_flow` when changing segment order, sections, routing, or converting a classification
segment to another type. List every segment to keep; an existing segment you aren't changing needs
only its `id`, and any field you leave out of an existing segment keeps its saved value, with two
exceptions: a saved next route is kept only when you also leave out `type`, and a multiple-choice
`question` and `choices` are kept only when you leave out both. To add,
rename, reorder, or remove sections, pass `sections` as the complete ordered list (existing sections
by `id`, new ones with a `localKey` and `name`) and place each new segment with `sectionId` or
`sectionLocalKey`.

When your organization has multiple-choice segments enabled, `edit_segments` action `add` accepts
`type: "multiple-choice"`, a `question`, and 2–10 ordered `choices` with stable `id` and `label`
values. Pass those same IDs on action `update` when editing or reordering choices; omit
`question` and `choices` to edit only the segment title or objective. `get_interview_guide`
returns the question, choice IDs and labels, and any choice-based display conditions. A referenced
choice cannot be removed until its affected display conditions are repaired. Use `edit_segments`
action `reorder` to change the order of a guide containing multiple-choice segments.
Set `selectionMode: "multiple"` on the multiple-choice configuration to let participants choose
one or more options; omitted mode means select one. Response tools return `selectedChoices` with
every recorded ID and its label at interview time for multi-select answers. Historical single-choice
answers continue to use `choiceId` and `choiceLabel`.

`update_guide_settings` action `response_modes` sets how participants respond. Pass `modes` as a
non-empty list: `["voice"]` for voice only, `["chat"]` for chat only, or `["voice", "chat"]` to let
each participant pick before the interview starts. A guide offers voice or chat until you change
it, and `get_interview_guide` returns the current list as `responseModes`. If chat is not
available for your workspace yet, the call says so and changes nothing. A chat response costs
1 credit however long it runs; a chat that ends before the participant answers a question costs
nothing. `list_responses` and `get_response` return each response's `responseMode`, `voice` or
`chat`. A chat response has no audio recording: its transcript is the typed conversation.

## Rate limits

Attune applies basic abuse protection, not a usage quota:

- **60 requests per minute** per connection.
- **300 requests per minute** per organization, shared across every connection in it.

Over the limit, Attune returns HTTP `429` with a `Retry-After` header in seconds. Normal
assistant use stays well under both.

On the free plan, `suggest_interview_objectives` also counts toward the hourly AI limit it shares
with the Attune web editor. Past that limit, a call with `refresh: true` returns a message saying
how many minutes to wait; a call without it still returns suggestions, which may be less tailored.

## Troubleshooting

<details>
<summary>"Connection failed" or "401 Unauthorized"</summary>

- Check that your Attune credentials are valid.
- Ensure your Attune organization has MCP enabled (contact your administrator).
- Sign out of the connector and reconnect to refresh the authorization.

</details>

<details>
<summary>The login window never opened</summary>

- Check your browser's popup blocker and allow popups for your assistant and the Attune login page.
- Disconnect and reconnect the server.

</details>

<details>
<summary>The assistant cannot see Attune's tools</summary>

- Confirm the client lists the server as connected, not only configured.
- Restart the client after editing a configuration file.
- If a tool call fails with a permission error, the connection was authorized without the scope
  that tool needs — reconnect and approve the full list.

</details>

## Support

Email [support@tryattune.ai](mailto:support@tryattune.ai). If you use ChatGPT, Codex, or Claude,
start with [the Attune plugin](/mcp/plugin/); for Cursor and other agents that read skills, see
[Attune skills for other agents](/mcp/skills/).

---

ChatGPT and Codex are trademarks of OpenAI. Claude is a trademark of Anthropic, PBC. Cursor, Visual
Studio Code, Windsurf, and Gemini are trademarks of their respective owners. Attune is not
affiliated with them.