Configuración del cliente

La disponibilidad depende del despliegue: se descubren 23 herramientas, o 24 con list_model_connections habilitada, y se registran 42 o 43 herramientas canónicas, respectivamente. La respuesta tools/list del servidor conectado es la referencia.

Esta guía conecta el servidor Minds MCP para investigación de mercado con los clientes de IA que admiten herramientas remotas. Usa https://getminds.ai/mcp como URL del servidor.

ChatGPT

Usa ChatGPT en la web. La disponibilidad y los permisos dependen de la cuenta y del espacio de trabajo; consulta las instrucciones MCP actuales de OpenAI.

Abre Settings → Apps y conecta Minds si está disponible para tu cuenta.
Para una conexión personalizada, activa Developer mode si está permitido, elige Apps → Create e introduce https://getminds.ai/mcp.
Elige OAuth e inicia sesión en Minds. Completa la búsqueda de herramientas y la configuración.
Selecciona Minds en una conversación nueva y pide la lista de tus Audiences. Las Studies más amplias requieren revisión y confirmación explícita antes de ejecutarse.

Los hosts web compatibles muestran resultados en la conversación. En un host móvil, el widget ofrece un enlace para continuar en Minds en lugar de controles interactivos.

Claude Desktop

Conector remoto (widgets según el cliente)

Abre Claude Desktop → Customize → Connectors (o Settings → Connections)
Añade https://getminds.ai/mcp como nuevo remote connector
Autoriza vía OAuth cuando se te pida — inicia sesión en tu cuenta de Minds
Las herramientas aparecen automáticamente tras la autorización

Opción B: Local Connector (API key, solo texto)

Añade esto a tu archivo de configuración (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Reinicia Claude Desktop. Las herramientas funcionan de inmediato, pero los widgets interactivos no están disponibles con local connectors.

Soporte de widgets en Claude

Las 23–24 herramientas anunciadas devuelven texto estructurado y enlaces clicables. El servidor registra además 19 herramientas canónicas de ciclo de vida para integraciones explícitas. La presentación de widgets depende del cliente y de su versión, por lo que la integración debe seguir siendo plenamente utilizable solo con resultados estructurados y de texto.

Claude Code (CLI)

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

Ejecuta /mcp en Claude Code y elige Authenticate para iniciar sesión con OAuth. Para usar una clave de API, añade --header "Authorization: Bearer minds_YOUR_API_KEY".

Codex

En la app de Codex, abre Settings → MCPs, añade https://getminds.ai/mcp y elige Authenticate. Deja vacíos los campos de token bearer y cabeceras para usar OAuth.

Con la CLI de Codex:

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

Para usar una clave de API, añade la cabecera Authorization: Bearer minds_YOUR_API_KEY.

Gemini CLI

Añade el servidor a ~/.gemini/settings.json:

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

Gemini CLI detecta OAuth en el servidor y abre la página de inicio de sesión en el primer uso. También puedes ejecutar /mcp auth minds.

Cursor

Abre Cursor Settings → MCP y añade un servidor nuevo, o añádelo a ~/.cursor/mcp.json:

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

Elige Login cuando Cursor lo solicite e inicia sesión en Minds.

VS Code (GitHub Copilot)

Ejecuta MCP: Add Server desde la paleta de comandos, elige HTTP e introduce https://getminds.ai/mcp. O añádelo a .vscode/mcp.json:

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

Inicia el servidor y permite que VS Code inicie sesión en Minds cuando lo solicite.

OpenRouter, Open WebUI y pasarelas compatibles con OpenAI

La autenticación depende del cliente que ejecuta la solicitud MCP y de la credencial que transmite. La clave API del proveedor del modelo no autentica ante Minds.

Transmisión del token OAuth

La API Responses de OpenAI acepta un token OAuth existente en el campo authorization de la herramienta MCP. Tu aplicación gestiona por separado la autorización y la renovación y envía el token en cada solicitud. Consulta la guía de autenticación MCP de OpenAI.

Open WebUI / OpenRouter

Configura una conexión Streamable HTTP a https://getminds.ai/mcp. Si el cliente o modo elegido no puede completar OAuth y transmitir el token, crea una clave Minds en Configuración → Claves API y configura Bearer mediante el almacén seguro del cliente. Prueba con list_audiences. Para OpenRouter y otras pasarelas, verifica su soporte MCP y el formato del descriptor; ser compatible con Chat Completions de OpenAI no garantiza MCP remoto.

Ejemplo de la API Responses de OpenAI

El ejemplo lee una clave API Minds del entorno. Para OAuth, sustituye headers por "authorization": os.environ["MINDS_OAUTH_ACCESS_TOKEN"] después de que tu aplicación obtenga un token Minds válido.

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)

Autenticación por API Key

Para acceso programático o clientes que no soportan OAuth:

Ve a Settings → API Keys en Minds
Crea una nueva API key (empieza por minds_)
Pásala como Bearer token: Authorization: Bearer minds_your_key_here

OAuth Discovery

Para desarrolladores que construyan integraciones MCP, los metadatos OAuth están disponibles en:

Endpoint	Descripción
`/.well-known/oauth-protected-resource`	Metadatos del recurso protegido (RFC 9728)
`/.well-known/oauth-authorization-server`	Metadatos del authorization server (RFC 8414)
`/oauth/register`	Dynamic Client Registration (RFC 7591)

Se requiere OAuth 2.1 con PKCE (S256). Los clientes públicos (token_endpoint_auth_method: "none") están soportados.

Los clientes nativos pueden registrar URIs de redirección loopback (http://127.0.0.1, http://localhost, http://[::1]); el puerto no se compara, así que un cliente puede escuchar en cualquier puerto libre (RFC 8252). Un cliente también puede usar un Client ID Metadata Document: una URL https como client_id que publica sus metadatos (client_id_metadata_document_supported: true). El endpoint de token acepta el client_id en el cuerpo de la solicitud o mediante autenticación HTTP Basic con el secreto vacío.

Resolución de problemas

Error "Authentication required"

Asegúrate de haber completado el flujo de autorización OAuth. Desconecta y vuelve a conectar tu cliente MCP para reautorizar.

Comprueba que el componente que ejecuta MCP transmite una credencial Bearer Minds válida. Reconecta OAuth o renueva el token mediante su cliente propietario; usa una clave API si la integración no transmite tokens OAuth. La clave de un proveedor o iniciar sesión en el host no sustituye una credencial Minds.

«Not authorized» para una Study, Audience o Mind que puedes abrir en Minds

El cliente MCP ha iniciado sesión con una cuenta de Minds distinta de la propietaria del elemento; el error indica la cuenta conectada. Vuelve a conectar el cliente con la cuenta propietaria o comparte el elemento con la cuenta conectada.

OAuth de Claude Desktop no se completa

Si el popup de OAuth se abre pero nunca se completa, prueba el enfoque de API key (Opción B anterior). El OAuth del remote connector de Claude Desktop puede ser intermitente.

Mind not found

Cuando uses mindName, asegúrate de que el nombre coincida estrechamente con tu Mind. El sistema usa fuzzy matching, pero requiere una puntuación de similitud razonable.

El Mind sigue entrenándose

Los Minds nuevos pueden tardar un momento en completar el entrenamiento. Usa get_mind_status para comprobar si el entrenamiento está completo antes de chatear.

Timeout en preguntas de study

Las preguntas de study con muchos audiences pueden tardar más de 2 minutos. Prueba a reducir el número de audiences o a simplificar la pregunta.

La exportación PDF no está lista

Las exportaciones son asíncronas. Consulta get_study_status con la misma studyId y los valores exactos exportKind, exportFormat y exportJobId devueltos por export_study. Comprueba el estado del trabajo y la URL de descarga; la duración varía. Un timeout de consulta no autoriza una exportación duplicada.

Los resultados siguen cargando o parecen incompletos

Los widgets reciben actualizaciones del host y consultan el estado automáticamente durante un periodo limitado cuando el host lo permite. Esto no garantiza streaming continuo de tokens. En otros casos, usa Actualizar si aparece, pide el estado de la Study existente o sigue el enlace Minds devuelto.

Usa get_study_status para una pregunta directa y get_study_run para un plan confirmado. Conserva el mismo studyId; una carga o un timeout no justifica ejecutar de nuevo. Indica las respuestas parciales y la cobertura incompleta. Que las preguntas estén cerradas no demuestra que cada Mind haya respondido.

Flujos de trabajo de n8n

Utilice el nodo de la comunidad Minds para n8n para crear Estudios, previsualizar planes de investigación, recuperar Estudios y resúmenes guardados, o exponer una operación a un Agente de IA. Instale n8n-nodes-minds en n8n autohospedado y conecte una clave API de Minds. El paquete está publicado en npm; la verificación de n8n está bajo revisión, por lo que aún no está disponible en n8n Cloud. Revise e inicie la investigación por separado en Minds.