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

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 Settings → Apps and connect Minds if it is available to your account.
2. For a custom connection, enable Developer mode where permitted, choose Apps → Create, and enter https://getminds.ai/mcp.
3. Choose OAuth and sign in to your Minds account. Complete the tool scan and app setup.
4. Select Minds in a new conversation and ask it to list your Audiences. Broader Studies require review and explicit confirmation before execution.

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 Desktop

Remote connector (widget support depends on the client)

1. Open Claude Desktop → Customize → Connectors (or Settings → Connections)
2. Add https://getminds.ai/mcp as a new remote connector
3. Authorize via OAuth when prompted — log in to your Minds account
4. Tools appear automatically after authorization

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 22 advertised tools return text responses with clickable links to open results in the Minds webapp. The server also registers 17 additional canonical lifecycle tools 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 mindsai https://getminds.ai/mcp \
  --header "Authorization: Bearer minds_YOUR_API_KEY"

Cursor

1. Open Cursor Settings → MCP
2. Add a new server with URL: https://getminds.ai/mcp
3. Authorize access when prompted

VS Code (GitHub Copilot)

1. Open VS Code Settings → Extensions → GitHub Copilot → MCP Servers
2. Add https://getminds.ai/mcp as a new server
3. Authorize when prompted

OpenRouter, Open WebUI, and OpenAI-compatible Gateways

For any host where the model provider (not the host) executes MCP calls server-side — e.g. an openai/* model accessed via OpenRouter, OpenAI's Responses API directly, or Open WebUI in Native function-calling mode — you must use API key authentication. OAuth is not supported on this path.

Why OAuth doesn't work here

When Open WebUI runs an openai/gpt-5.2 agent in Native mode, it ships the MCP tool descriptor to OpenAI/OpenRouter as part of the request. OpenAI's server-side MCP runner (running on Azure, identifiable by User-Agent: python-httpx/*) then calls our /mcp endpoint directly. That runner only attaches static headers configured at tool-registration time — it does not perform the MCP OAuth handshake (RFC 9728 / 8414 / 7591). Open WebUI's OAuth — forwards system user's access token mode is therefore a no-op: the user's token never leaves Open WebUI.

Result: Minds receives the request with no Authorization header and returns:

401 Unauthorized
www-authenticate: Bearer resource_metadata="https://getminds.ai/.well-known/oauth-protected-resource"
{"error":{"code":-32001,"message":"Authentication required. Connect your Minds account via OAuth or provide an API key."}}

Open WebUI setup

1. Generate an API key at Settings → API Keys (format minds_…).
2. In Open WebUI: Admin → Settings → Tools → + Connection.
3. Set:
   • Type: Streamable HTTP (MCP)
   • URL: https://getminds.ai/mcp
   • Authentication: Bearer (not OAuth)
   • Token: your minds_… key
4. Save the connection.
5. In your agent's Werkzeuge / Tools tab, attach the Get Minds tool.
6. Test by asking the agent to list your Minds.

If you keep Authentication: OAuth, calls will succeed only when Open WebUI itself executes the tool (i.e. Function calling = Default, not Native) and the upstream model can be re-prompted with the tool result. Most users want Native mode — so use a Bearer key.

OpenRouter direct (programmatic)

When calling OpenRouter's chat completions API and attaching the Minds MCP server, pass the API key in the static headers field of the tool descriptor:

{
  "type": "mcp",
  "server_label": "minds",
  "server_url": "https://getminds.ai/mcp",
  "headers": {
    "Authorization": "Bearer minds_YOUR_API_KEY"
  }
}

Same applies to OpenAI's Responses API directly:

from openai import OpenAI
client = OpenAI()
client.responses.create(
    model="gpt-5.2",
    input="List my Minds",
    tools=[{
        "type": "mcp",
        "server_label": "minds",
        "server_url": "https://getminds.ai/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['MINDS_API_KEY']}"},
    }],
)

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.

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.

Troubleshooting

"Authentication required" error

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

If you're calling Minds via OpenRouter, Open WebUI in Native mode, or OpenAI's Responses API directly, OAuth is not supported on that path — the model provider's server-side MCP runner cannot perform the OAuth handshake. Switch your MCP connection to Bearer / API key authentication with a minds_… key. See OpenRouter, Open WebUI, and OpenAI-compatible Gateways above.

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 sparkName, 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

PDF reports are generated asynchronously. Use get_study_status to check the export status. Generation typically takes 30-60 seconds.

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.