Conectar a ArtificialQA por MCP

¿Qué camino uso?

Setup OAuth (recomendado)

Necesitas tener mcp-remote instalado una vez en tu máquina. Es el proxy chico que hace de puente entre el transporte stdio de tu cliente y el endpoint HTTP de ArtificialQA, y maneja el flujo OAuth del navegador.

npm install -g mcp-remote

Después pega esto en el archivo de configuración de tu cliente:

{
  "mcpServers": {
    "artificialqa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.artificialqa.com/api/v1/mcp"
      ]
    }
  }
}

Dónde vive el archivo de config

Qué pasa la primera vez que conectas

1. Abres tu cliente MCP (por ejemplo, cierras y vuelves a abrir Claude Desktop después de editar la config).
2. mcp-remote descubre el servidor de auth de ArtificialQA.
3. Tu navegador por defecto se abre en /oauth/authorize.
4. Si no estás logueado en ArtificialQA en ese navegador, te manda a /login. Inicia sesión (y pasa el 2FA si tu cuenta lo requiere).
5. Vuelves a la pantalla de consentimiento: eliges el proyecto sobre el que el cliente va a operar, eliges Read only o Read + write (tu rol en el proyecto es el techo), clic en Allow.
6. El navegador muestra una página con el branding "Authorization successful". Puedes cerrar la pestaña.
7. Tu cliente MCP ahora marca el servidor como conectado. Prueba list_test_plans o list_test_cases para confirmar.

A partir de ahí, mcp-remote cachea tus tokens en ~/.mcp-auth/ y los rota solo. No vas a volver a ver el navegador por ~30 días, o hasta que revoques la sesión.

Nota Windows

Si npx -y mcp-remote falla con 'C:\Program' is not recognized, es cmd /C trabándose con el espacio en C:\Program Files\nodejs\npx.cmd. Apuntá directamente al shim bajo %APPDATA%\Roaming\npm\:

{
  "mcpServers": {
    "artificialqa": {
      "command": "C:\\Users\\<usuario>\\AppData\\Roaming\\npm\\mcp-remote.cmd",
      "args": ["https://app.artificialqa.com/api/v1/mcp"]
    }
  }
}

"No accessible projects" / "No organizations"

Te topaste con uno de los estados de error de la pantalla de consentimiento. Causas frecuentes:

Cierra la pestaña, sal desde el menú desplegable, entra con la cuenta correcta y reinicia tu cliente MCP para volver a disparar el flujo.

Setup con API key estática (provisionada por un admin)

Si tu org admin te dio una key aqa_*, pega esto en su lugar:

{
  "mcpServers": {
    "artificialqa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.artificialqa.com/api/v1/mcp",
        "--header",
        "Authorization: Bearer aqa_v0C5AyynN..."
      ]
    }
  }
}

La única diferencia respecto al snippet de OAuth es el flag --header Authorization: Bearer ... al final. No hay flujo de navegador en la primera conexión — la key te autentica de inmediato. La key está atada a un solo proyecto, así que el cliente solo ve datos dentro de ese proyecto.

Clientes HTTP nativos (Cursor sin stdio)

Cursor y Continue también pueden hablar Streamable HTTP directamente, sin mcp-remote. Misma idea, otra forma de config:

{
  "mcpServers": {
    "artificialqa": {
      "url": "https://app.artificialqa.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer aqa_v0C5AyynN..."
      }
    }
  }
}

HTTP nativo solo funciona con keys estáticas — Cursor y Continue no manejan el handshake OAuth por sí mismos. Si quieres OAuth en esos clientes, usá el snippet stdio de arriba y dejá que mcp-remote maneje el flujo.

Verificar la conexión (curl)

No necesitas un cliente para confirmar que el endpoint responde. Con una key estática:

curl https://app.artificialqa.com/api/v1/mcp \
  -X POST \
  -H "Authorization: Bearer aqa_v0C5AyynN..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Esperá un array result.tools con cada herramienta a la que tienes acceso. Un 401 con header WWW-Authenticate significa que la key fue rechazada (revisá el valor y que tu org tenga MCP habilitado). Un 403 con mcp_disabled significa que el org admin tiene que activar la feature de MCP.

Los tokens OAuth (oat_*) funcionan igual desde curl, pero tienes que sacar uno del cache que mcp-remote escribe — no hay UI para copiar tu access token, porque justamente el punto es que nunca lo veas.

Problemas frecuentes

"Authorization successful" nunca aparece y el navegador queda colgado en consent. Probablemente el cliente MCP hizo timeout (~60s en el handshake inicial). Cierra y reabre tu cliente MCP para arrancar el flujo con un proceso fresco de mcp-remote. Ten la contraseña y el TOTP a mano para que el flujo termine bien por debajo de los 60s.

La pestaña se abre cada vez que arranco el cliente. mcp-remote no pudo escribir su cache. Verificá que ~/.mcp-auth/ esté escribible por tu usuario. En macOS, a veces el sandbox de Claude Desktop necesita que le vuelvas a dar acceso al home directory.

"redirect_uri not registered for this client". La redirect URI registrada por mcp-remote ya no coincide con el puerto en el que está escuchando (típicamente después de borrar el cache a mano). Limpiá el cache y dejá que se vuelva a registrar:

rm -rf ~/.mcp-auth                                          # macOS / Linux
Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp-auth"   # Windows PowerShell

Después reabre el cliente MCP.

'C:\Program' is not recognized en Windows. Mira la nota Windows en la sección de setup OAuth de arriba — usá la ruta al shim .cmd en lugar de npx.

Referencia

• Referencia de la API REST pública — los mismos primitivos sobre una superficie REST para CI/CD.
• Integraciones — cómo MCP encaja en la historia más amplia de integraciones.
• Seguridad y compliance — semánticas de audit, techos de scope y revocación break-glass.