Minds MCP Setup for ChatGPT, Claude, Cursor, and VS Code

Every client below sees the same 45 advertised tools, read from the live server. Treat the connected server’s tools/list response as authoritative.

This guide connects the Minds MCP server for market research to the AI clients that support remote tools. Use https://getminds.ai/mcp as the server URL.

ChatGPT

Use ChatGPT on the web. Availability and permissions depend on your account and workspace; follow OpenAI's current MCP setup guidance.

1. Open Plugins and choose Add → Create MCP App. If the option is missing, turn on developer mode or ask your workspace admin to allow custom MCP apps.
2. Name it Minds, set Server URL to https://getminds.ai/mcp and Authentication to OAuth, confirm the risk notice, and click Create.
3. Click Continue to Minds, sign in to your Minds account, and choose Allow.
4. In a new conversation, type @Minds and ask it to list your Audiences. Broader Studies require review and explicit confirmation before execution.

If Minds appears in the plugin directory for your account, you can also add it from Plugins and sign in the same way.

In the ChatGPT desktop app, open Plugins and choose Add → Add MCP server. Set the type to Streamable HTTP and the URL to https://getminds.ai/mcp, click Save, then Restart, and choose Authenticate to sign in to Minds.

The ChatGPT setup guide walks through every screen, including the plugin directory and desktop app options.

Compatible web hosts can display Minds results inline. On a mobile host, a rendered Minds widget provides a link to continue in Minds instead of interactive controls.

Claude (claude.ai and Claude Desktop)

Remote connector (widget support depends on the client)

Custom connectors work the same way on claude.ai and in Claude Desktop, and sync between them.

1. Open Customize → Connectors, click +, and choose Add custom connector
2. Enter https://getminds.ai/mcp as the remote MCP server URL and click Add
3. Click Connect, sign in to your Minds account, and choose Allow
4. In a conversation, enable Minds from + → Connectors

On Team and Enterprise plans, an owner first adds the connector under Organization settings → Connectors; members then connect their own Minds account under Customize → Connectors.

Option B: Local Connector (API key, text-only)

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mindsai": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://getminds.ai/mcp",
        "--header",
        "Authorization: Bearer minds_YOUR_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop. Tools work immediately but interactive widgets are not available with local connectors.

Widget Support in Claude

The advertised tools return text responses with clickable links to open results in the Minds webapp. The server also keeps further canonical lifecycle tools callable for explicit integrations; see the tools reference. Interactive widget behavior depends on the client and client version, so integrations must remain fully usable from structured/text results without assuming a widget rendered.

Claude Code (CLI)

claude mcp add --transport http minds https://getminds.ai/mcp

Run /mcp in Claude Code, select minds, and choose Authenticate to sign in with OAuth. An API key is optional: to use one instead, add --header "Authorization: Bearer minds_YOUR_API_KEY" to the command.

Codex

With the Codex CLI:

codex mcp add minds --url https://getminds.ai/mcp
codex mcp login minds

codex mcp login opens the Minds sign-in page. Codex registers itself with a Client ID Metadata Document, so you don't need a client ID or secret.

In the Codex app or IDE extension, open Settings → MCP servers, choose Add server, pick Streamable HTTP, and enter https://getminds.ai/mcp. Save, restart, and choose Authenticate.

To use an API key instead, set bearer_token_env_var = "MINDS_API_KEY" under [mcp_servers.minds] in ~/.codex/config.toml and export the key in that variable.

Gemini CLI

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

{
  "mcpServers": {
    "minds": { "httpUrl": "https://getminds.ai/mcp" }
  }
}

Or run gemini mcp add --transport http minds https://getminds.ai/mcp. Gemini CLI discovers OAuth from the server and opens the sign-in page on first use. You can also run /mcp auth minds.

Google Antigravity

Add the server to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in a workspace). Antigravity needs serverUrl; it does not accept url or httpUrl:

{
  "mcpServers": {
    "minds": { "serverUrl": "https://getminds.ai/mcp" }
  }
}

Or run agy mcp add --type http minds https://getminds.ai/mcp. To sign in, open Settings → Customizations, choose Authenticate next to minds, then paste the code shown after sign-in. See Minds in Google Antigravity for the plugin install and API keys.

Cursor

1. Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "minds": { "url": "https://getminds.ai/mcp" }
  }
}

2. Authenticate when Cursor prompts, and sign in to Minds.

VS Code (GitHub Copilot)

1. Run MCP: Add Server from the Command Palette, choose HTTP, and enter https://getminds.ai/mcp. Or add it to .vscode/mcp.json:

{
  "servers": {
    "minds": { "type": "http", "url": "https://getminds.ai/mcp" }
  }
}

2. Start the server and allow VS Code to sign in to Minds when prompted. The Minds tools then appear in Copilot Chat in agent mode.

Windsurf

In the Cascade panel, open the … menu and choose Open MCP config file. Add Minds under mcpServers:

{
  "mcpServers": {
    "minds": { "serverUrl": "https://getminds.ai/mcp" }
  }
}

Save the file, then sign in to Minds when Windsurf prompts. To use an API key instead, add "headers": { "Authorization": "Bearer ${env:MINDS_API_KEY}" } to the entry.

OpenRouter, Open WebUI, and OpenAI-compatible Gateways

Authentication depends on which client executes the MCP request and which credential it forwards. A provider’s API key does not authenticate the request to Minds.

OAuth token forwarding

OpenAI’s Responses API accepts an existing OAuth access token in the MCP tool’s authorization field. Your application handles authorization and token refresh separately and supplies the token on each request. See OpenAI’s remote MCP authentication guide.

Open WebUI / OpenRouter

Configure a remote Streamable HTTP connection to https://getminds.ai/mcp. If the selected client or execution mode cannot complete OAuth and forward its access token, create a Minds API key in Settings → API Keys and configure Bearer authentication through the client’s secret store. Test with list_audiences. For OpenRouter and other gateways, check the gateway’s current MCP support and descriptor format; OpenAI-compatible chat completions alone do not guarantee remote MCP support.

OpenAI Responses API example

This example reads a Minds API key from the environment. For OAuth, replace headers with "authorization": os.environ["MINDS_OAUTH_ACCESS_TOKEN"] after your application has obtained a valid Minds access token.

import os
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5.2",
    input="List my Audiences",
    tools=[{
        "type": "mcp",
        "server_label": "minds",
        "server_url": "https://getminds.ai/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['MINDS_API_KEY']}"},
        "allowed_tools": ["list_audiences"],
        "require_approval": "never",
    }],
)
print(response.output_text)

API Key Authentication

For programmatic access or clients that don't support OAuth:

1. Go to Settings → API Keys in Minds
2. Create a new API key (starts with minds_)
3. Pass it as a Bearer token: Authorization: Bearer minds_your_key_here

Never paste a real key into a prompt, checked-in configuration, screenshot, or shared log. Prefer environment-variable interpolation or the client's encrypted secret store. An MCP session cannot mint or revoke its own API key by design.

Scopes

OAuth clients ask for the OpenID basics (openid, email, profile) and the Minds scopes below. The Minds consent screen shows each scope in product terms before you choose Allow. A client that asks for no scope receives all of them.

OAuth Discovery

For developers building MCP integrations, OAuth metadata is available at:

OAuth 2.1 with PKCE (S256) is required. Public clients (token_endpoint_auth_method: "none") are supported.

Native clients may register loopback redirect URIs (http://127.0.0.1, http://localhost, http://[::1]); the port is not matched, so a client can listen on any free port (RFC 8252). A client can also use a Client ID Metadata Document: an https client_id URL that publishes its metadata (client_id_metadata_document_supported: true). The token endpoint accepts the client_id in the request body or as HTTP Basic authentication with an empty secret.

Troubleshooting

"Authentication required" error

Make sure you've completed the OAuth authorization flow. Disconnect and reconnect your MCP client to re-authorize.

Check that the component executing MCP calls forwards a valid Minds Bearer credential. Reconnect OAuth or refresh the access token through its owning client; use an API key if the integration cannot forward OAuth tokens. A provider API key or a completed host login is not a Minds credential.

"Not authorized" for a Study, Audience or Mind you can open in Minds

The MCP client is signed in to a different Minds account than the one that owns the item; the error names the connected account. Reconnect the client with the owning account, or share the item with the connected account.

Claude Desktop OAuth not completing

If the OAuth popup opens but never completes, try using the API key approach (Option B above). Claude Desktop's remote connector OAuth can be intermittent.

Mind not found

When using mindName, ensure the name closely matches your Mind. The system uses fuzzy matching but requires a reasonable similarity score.

Mind still training

New Minds may take a moment to complete training. Use get_mind_status to check if training is complete before chatting.

Study question timeout

Study questions with many Audiences may take over 2 minutes. Try reducing the number of Audiences or simplifying the question.

PDF export not ready

Exports run asynchronously. Poll get_study_status with the same studyId and the exact exportKind, exportFormat and exportJobId returned by export_study. Inspect the returned job state and download URL; generation time varies. A polling timeout does not authorize a duplicate export.

Results are still loading or look incomplete

Result widgets consume updates from the host and use bounded automatic status polling where the host permits it. This is not a guarantee of continuous token streaming. On other hosts, or after automatic polling stops, use Refresh when shown, ask the assistant to check the existing Study, or follow the returned Minds link.

Use get_study_status for a direct question and get_study_run for a confirmed research plan. Keep the same studyId; a loading widget or timeout is not a reason to submit the Study again. Report partial answers and response coverage as incomplete. A settled question count alone does not prove every Mind answered.

n8n workflows

For n8n, follow the community-node installation and credential steps. Install the package on a self-hosted instance and select a Minds API credential in each node. This setup uses an API key rather than the MCP OAuth connection described above.