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

# MCP: Setup

> Connect Claude Desktop, Claude Code, ChatGPT, Cursor, Copilot, or any MCP client to Great Question via OAuth with a single server URL.

First, a workspace admin turns on MCP on the [AI & MCP page](https://greatquestion.co/ai_preferences) in Settings. Only admins can see this page, and MCP has to be included in your plan; if it isn't, the toggle is locked. Second, the admin decides whether PII should be hidden via the MCP. This option appears once MCP is on, and it applies to every MCP connection in the workspace:

![Image](https://mintcdn.com/greatquestion/fbrMVf7KfvKwxDw_/support/images/image-28.png?fit=max\&auto=format\&n=fbrMVf7KfvKwxDw_\&q=85\&s=1bb2f1fc9ed17a50e38c77a1b83ed129)

All clients connect to the same server URL:

```text theme={null}
https://greatquestion.co/api/mcp/v1
```

Admins, creators, and observers can connect. The connection uses OAuth: you'll authenticate through your browser with your existing Great Question credentials and pick the workspace to connect. No API keys or secrets to manage. If MCP is included in your plan but switched off, an admin can turn it on right from that sign-in screen; anyone else sees which admins to ask.

### Claude Desktop

1. Open **Settings → Connectors → Add custom connector**.
2. Enter the name `Great Question` and the server URL above.
3. Click **Save**, then **Connect**. Authenticate via your browser.
4. Restart Claude Desktop. Great Question tools will appear when you start a new chat.

### Claude Code

Run in your terminal:

```text theme={null}
claude mcp add --transport http GreatQuestion https://greatquestion.co/api/mcp/v1
```

### ChatGPT/Codex Desktop app

1. Go to **Settings → Plugins → MCPs**.
2. Click **+ Add server**, then enter:
   * **Name:** Great Question
   * **Type:** Streamable HTTP
   * **URL:** `https://greatquestion.co/api/mcp/v1`
   * Leave other fields blank
3. Click **Save**, and then **authenticate.**

### Cursor

1. Open Cursor Settings (**Cmd/Ctrl + Shift + J**), then select **MCP** from the sidebar.
2. Click **+ New MCP Server** to open your `mcp.json` file.
3. Add the following:

```text theme={null}
{
  "mcpServers": {
    "great-question": {
      "url": "https://greatquestion.co/api/mcp/v1"
    }
  }
}
```

4. Save the file, then click **Connect** on the settings page. Authenticate via your browser.

### Copilot

There are two ways to connect your agent to an MCP server in Copilot Studio:

* [Add the MCP server in Copilot Studio by using the *MCP onboarding wizard* ](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent#option-1-use-the-mcp-onboarding-wizard-recommended)(recommended)
* [Create a custom connector to your server through Power Apps](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent#option-2-create-a-custom-mcp-connector-in-power-apps)

To connect your agent using the MCP onboarding wizard, please follow these steps:

1. Go to the **Tools** page for your agent.
2. Select **Add a tool**.
3. Select **New tool**.
4. Select **Model Context Protocol**. The MCP onboarding wizard appears.
5. Fill in the required fields **Server name**, **Server description**, and **Server URL**. Write a brief, but clear description of what your MCP server does. The agent orchestrator uses this information to identify whether to call your server at runtime.
   1. Server name: Great Question
   2. Server URL: [https://greatquestion.co/api/mcp/v1](https://greatquestion.co/api/mcp/v1)
   3. Server description: Give the agent read and write access to Great Question's research platform — studies, screeners, candidates, sessions, transcripts, highlights, and insights. Use it to create and configure interview, survey, and unmoderated studies, manage participants and recruitment, pull transcripts and screener responses, and search past research for findings and highlights. Feel free to adjust the server description as desired.
6. Select the authentication type for your MCP server. Great Question requires authentication, so don't choose **None**. Use one of:
   1. **OAuth 2.0** (recommended): Great Question supports dynamic client registration. [Configure OAuth 2.0 authentication](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent#configure-authentication-with-your-mcp-server)
   2. **API key**: send a Great Question API token in the `Authorization` header as `Bearer <token>`. See [Connecting an agent](#connecting-an-agent-no-human-login-required) for how to create one. [Configure API key authentication](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent#configure-authentication-with-your-mcp-server)
7. Create a new connection and add the MCP server to your agent.
   1. On **Add tool**, select **Create a new connection** for your MCP server or use an existing one.
   2. Select **Add to agent** to finish adding the MCP server to your agent.

## Verifying your connection

Once connected, run through these quick checks in your MCP client:

1. **See your studies.** Ask for your recent studies. You should see titles, statuses, and IDs you recognize.
2. **Find participants.** Ask for the participants in one of those studies. Names and emails should appear as expected, unless your admin turned on PII hiding for the MCP, in which case they're masked.
3. **Pull a transcript.** Ask for transcripts from that study, then request the full content of one. Look for speaker labels and timestamps.
4. **Connect the dots.** Pick a participant and ask what sessions they had and what their transcripts say.
5. **Try a write action**. Create a test candidate or draft study to confirm write access is working. You can delete it afterward. Write actions follow your role, so an observer's test write may be refused.
6. **Try a repo session.** Ask for recent repo sessions, pick one, and request its transcript.

If something doesn't work, see **Troubleshooting** below.

## Connecting an agent (no human login required)

Beyond the browser-based OAuth flow above, an agent can now connect to Great Question entirely on its own, without a person driving it. Give the agent a secure API token once, and it authenticates automatically in the background whenever it needs to, with no repeated logins and no OAuth window to click through.

To set this up:

1. A workspace admin creates a token under **Settings → API Tokens**. This page is available to admins on plans that include API access.
2. Copy the token immediately. The page shows the full token only if loaded within 20 seconds of creation; later page loads show a masked version. If you miss that window, revoke the token and create a new one.
3. Configure the agent to send it with every request to the server URL above, in the `Authorization` header as `Bearer <token>`.

Each token belongs to one workspace, expires after one year, and only works while MCP is turned on for that workspace. If your workspace restricts API access to certain IP addresses, that restriction applies to the agent too.

The agent only has access to what the token's associated user can already see in Great Question. Permissions and privacy work exactly like a normal login: if that user can't see a given study, session, or candidate, the agent can't either.

> [!NOTE]
>
> This is separate from the OAuth setup above, which is for a person actively using an MCP client. Use an API token when you want an agent to run unattended. For example, checking recruitment status overnight or applying a screener template as part of an automated workflow.

## Troubleshooting

**OAuth window doesn't appear?** Make sure your browser allows popups from your MCP client. Some browsers block the OAuth redirect by default.

**Tools not showing up?** Restart your MCP client after saving the configuration. If tools still don't appear, ask a workspace admin to check that MCP is turned on in **Settings → AI & MCP**. If the toggle is locked, MCP isn't included in your plan; contact your Great Question account team.

**An agent's API token stops working?** Tokens expire one year after they're created, and the admin who created the token can revoke it under **Settings → API Tokens**. Tokens can't be rotated, so create a new one and update it in the agent's configuration. Also check that MCP is still turned on for the workspace. Since the agent only sees what its associated user can see, also confirm that user's permissions haven't changed.

**Can I query against two different Great Question workspaces?** Each MCP connector can only be linked to one workspace at a time. If you work across multiple workspaces, you have two options:

* **Use a single connector and re-authenticate when switching.** Disconnect the connector and authenticate it again to point it at a different workspace.
* **Create a separate connector for each workspace.** When you create a connector, you can give it a name to make the workspaces easy to tell apart, for example:
  * `GQ-product-lab`
  * `GQ-dtx`

**Still need help?** Contact us at [support@greatquestion.co](mailto:support@greatquestion.co) — median response time is 19 minutes during [support hours](https://greatquestion.co/features/about-our-support-team).
