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

# MCP Server

> Connect an AI assistant to Conveo, choose OAuth or limited API-key access, and manage the connection.

Conveo's remote Model Context Protocol (MCP) server lets compatible AI assistants read research and perform authorized study-design and analysis actions. OAuth connections can expose tools that change studies. Review an assistant's proposed changes before authorizing those actions.

## Connection details

| Field                                       | Value                                                                           |
| ------------------------------------------- | ------------------------------------------------------------------------------- |
| Server URL                                  | `https://app.conveo.ai/api/mcp`                                                 |
| Transport                                   | Streamable HTTP                                                                 |
| Authentication                              | OAuth for interactive assistants; Bearer API key for the limited tool set below |
| Preconfigured OAuth client ID, if requested | `7326f7bf-48d6-4b75-a418-0c9c0d8eb901`                                          |
| OAuth client secret                         | Leave empty for the public client                                               |

During OAuth sign-in, select the Conveo organization to authorize. Tool requests run as that user in that organization and check current access. Leaving the organization, losing relevant study access, or revoking the session can prevent further calls.

## Adding to Claude Code

Add the remote server with Claude Code's HTTP transport:

```bash theme={null}
claude mcp add --transport http Conveo https://app.conveo.ai/api/mcp
```

Open Claude Code, run `/mcp`, and complete the Conveo sign-in flow. If your client requires the preconfigured ID, add `--client-id 7326f7bf-48d6-4b75-a418-0c9c0d8eb901` when configuring the server. Do not add a client secret.

Use Claude Code's [MCP configuration guide](https://code.claude.com/docs/en/mcp) for configuration scope, managing existing entries, and client-version troubleshooting.

## Adding to Claude Desktop

Use Claude's remote **Connectors** settings to add a custom connector with the server URL above, then authorize Conveo. In Conveo, **Settings → Organization → Integrations → Add to Claude** opens the custom-connector flow with the URL prefilled.

Remote connectors use Claude's connector flow rather than the local-server JSON configuration. See [Claude's custom remote connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for current plan and organization-admin requirements. The same remote connector can be used on Claude's web interface where available.

## Adding to other MCP clients

Choose a client supporting Streamable HTTP and the server's OAuth authorization flow. Dynamic registration accepts supported local callbacks and allowlisted hosted callbacks. An arbitrary hosted client's redirect URL may require Conveo setup; contact support if registration fails.

For supported API-key clients, send `Authorization: Bearer <organization-api-key>` through the client's secret configuration. An API key does not expose the full OAuth tool set.

## Available tools

OAuth exposes the [MCP tool reference](/docs/api-reference/mcp-tools), subject to the connected user's permissions and feature prerequisites. It covers study design, questions, stimuli, quotas, analysis sessions, interviews, clips, facets, and Storylines. Tool discovery provides current input schemas; use returned IDs instead of inventing identifiers.

An organization API key exposes exactly these tools:

* `list_studies`
* `get_study`
* `list_interviews`
* `list_storylines`
* `list_storyline_insights`
* `search_clips`

For MCP, the key acts as its creating user and requires that user to remain in the organization. Older keys without a recorded creating user cannot authenticate to MCP; create a replacement if needed. MCP study reads can include draft and in-field studies, unlike the completed-study REST endpoints.

## Manage and revoke connections

Organization admins can open **Settings → Organization → API keys** to review MCP sessions and revoke a connection. API-key connections are revoked by deleting their API key. Disconnect the connector in the assistant client as well when it is no longer needed.

OAuth access tokens expire and are refreshed by compatible clients. If authentication stops working, reconnect and confirm the selected organization. A successful sign-in does not override study permissions or feature gates.

## Troubleshooting

| Symptom                          | Check                                                                                              |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| Only six tools appear            | The connection uses an API key; use OAuth for authorized write and analysis tools.                 |
| Study not found or inaccessible  | Confirm the organization, study ID, and connected user's current study access.                     |
| Hosted-client registration fails | Its callback may not be allowlisted. Contact Conveo rather than reusing another client's identity. |
| A mutation timed out             | Read back the study before retrying; an operation may have completed despite the lost response.    |
| Analysis returns an error        | Check session studies, source access, and the tool error message.                                  |

For scripts retrieving completed research data, see the [REST API](/docs/api-reference/index).