Conectar cualquier cliente MCP por HTTP

Lo que necesitas antes de empezar

• Una API key atkr_... creada en el dashboard, en la pantalla de API keys del workspace. La clave es la identidad: el workspace sale de ella, no de un parámetro.
• La URL del endpoint: https://mcp.ai-tasker.theboomer.dev/mcp. No hay rutas por herramienta ni por recurso.
• curl y algo que sepa leer JSON. Los ejemplos usan jq solo para extraer valores.
• Un cliente HTTP que soporte POST con cuerpo JSON y cabeceras de respuesta: el transporte es Streamable HTTP, no un WebSocket.

El endpoint no es un REST. tools/list y tools/call son métodos JSON-RPC dentro de un POST a /mcp; llamar a /mcp/lista-de-tools devuelve 404 aunque la herramienta exista.

Paso 1: initialize abre la sesión

La primera petición va sin mcp-session-id y con el cuerpo initialize. El servidor valida la API key en ese momento: una clave revocada, archivada o inexistente falla aquí con 401/403, no en la primera herramienta. Ese detalle ahorra el clásico "conectado pero todo falla".

Guarda la cabecera de respuesta: contiene el id de sesión.

curl -sD /tmp/mcp-headers.txt -X POST https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer atkr_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "mi-cliente", "version": "1.0.0" }
    }
  }'

grep -i "mcp-session-id" /tmp/mcp-headers.txt

La respuesta trae serverInfo con el nombre y la versión del servidor, y las capacidades que anuncia. La versión de protocolo que negocies debe ser del mismo major que la del SDK del servidor; si tu cliente es antiguo, no inventes el campo: deja que el servidor proponga la suya.

Paso 2: la cabecera mcp-session-id

Ese id es obligatorio en todas las peticiones siguientes. Sin él, el servidor no puede resolver la sesión y responde 404 NOT_FOUND con el mensaje "Invalid or expired Mcp-Session-Id". Es el error que más tiempo cuesta porque parece un fallo de permisos y es solo una cabecera olvidada.

Reutiliza el id en cada llamada posterior.

SID=$(grep -i "mcp-session-id" /tmp/mcp-headers.txt | tr -d '\r' | awk '{print $2}')
echo "$SID"

Paso 3: avisa de que estás inicializado

El protocolo pide una notificación notifications/initialized antes de usar las herramientas. No lleva id porque no espera respuesta, y la respuesta HTTP puede llegar vacía o con 202: no la interpretes como error.

Notificación sin id: es un aviso, no una petición.

curl -s -X POST https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer atkr_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Paso 4: descubre las herramientas

tools/list devuelve las herramientas con su inputSchema. Son 40 en el servidor desplegado, y el catálogo público de la web se genera del mismo código, así que si un nombre no aparece aquí, no existe.

Lista de herramientas; con jq se ve solo el nombre y la descripción.

curl -s -X POST https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer atkr_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' \
  | jq -c '.result.tools[] | {name, description}'

Paso 5: llama una herramienta

El cuerpo es tools/call con name y arguments. Las herramientas que necesitan workspace lo resuelven desde la API key, así que projectId o workspaceId se pueden omitir cuando el agente solo alcanza uno.

Lectura de proyectos: la operación más barata para comprobar que todo está bien.

curl -s -X POST https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer atkr_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": { "name": "list_projects", "arguments": {} }
  }'

Si pasas un código de tarea (TSK-42) en vez de un id, incluye projectId o workspaceId: el servidor necesita un ámbito para resolver el código y sin él responde con el error que lo explica.

Errores del transporte y qué significan

Respuesta	Causa	Qué hacer
401 UNAUTHORIZED	Falta la cabecera Authorization	Añadir Authorization: Bearer atkr_...
401 INVALID_API_KEY	La clave no existe, está revocada o el workspace está archivado	Crear una clave nueva en el dashboard; no reintentar
404 NOT_FOUND "Invalid or expired Mcp-Session-Id"	Falta mcp-session-id o la sesión se perdió	Repetir initialize y reutilizar el id nuevo
400 INVALID_JSON / EMPTY_BODY	Cuerpo mal formado o vacío	Enviar JSON-RPC válido en el POST
405 METHOD_NOT_ALLOWED	Método distinto de GET/POST/DELETE sobre /mcp	Usar POST para JSON-RPC, GET solo para el stream SSE
429 OPERATION_QUOTA_EXCEEDED	Cupo mensual del workspace agotado	Ampliar con créditos (acción humana) o esperar al siguiente periodo
429 AGENT_DAILY_REQUEST_QUOTA_EXCEEDED	Guarda diaria anti-abuso	Esperar a las 00:00 UTC; no se compra

Cerrar la sesión

Cuando termines, cierra con DELETE /mcp y la misma cabecera de sesión. El servidor borra la entrada y libera recursos; no cerrar no rompe nada, pero deja sesiones colgadas contando para el límite del proceso.

Cierre ordenado.

curl -s -X DELETE https://mcp.ai-tasker.theboomer.dev/mcp \
  -H "Authorization: Bearer atkr_tu_clave" \
  -H "mcp-session-id: $SID" -o /dev/null -w "%{http_code}\n"

Comprobaciones antes de culpar al cliente

• GET https://mcp.ai-tasker.theboomer.dev/health responde 200 sin autenticación: si falla, el problema no es tu cliente.
• GET https://api.ai-tasker.theboomer.dev/agent/service-info responde sin clave y describe límites y canales: sirve para saber qué plan está aplicando el backend.
• El mcp-session-id que estás enviando es el de la última respuesta de initialize, no uno guardado de una sesión anterior.
• La cabecera Accept incluye text/event-stream: el transporte puede responder con streaming y un cliente que solo acepta JSON falla en la lectura.
• Si copiaste el comando de esta página, sustituye atkr_tu_clave por una clave real: el ejemplo no lleva credenciales.

Conectar un cliente MCP genérico a AI Tasker

Handshake completo por HTTP contra el endpoint MCP: abrir sesión, descubrir herramientas y llamar una, sin SDK.

1. Comprueba el servicio

   GET /health del servidor MCP y GET /agent/service-info de la API: si responden, el problema estará en el cliente.

2. Abre la sesión con initialize

   POST a /mcp con la cabecera Authorization y el cuerpo initialize, sin mcp-session-id. La clave se valida aquí.

3. Guarda el mcp-session-id

   La cabecera de la respuesta trae el id; envíalo en todas las peticiones siguientes.

4. Envía notifications/initialized

   Notificación sin id para avisar de que el handshake terminó.

5. Lista y llama herramientas

   tools/list para el catálogo real y tools/call con name y arguments.

6. Cierra la sesión

   DELETE a /mcp con la misma cabecera de sesión.

Preguntas frecuentes

¿Necesito un SDK de MCP para conectarme?

No. El endpoint habla JSON-RPC sobre HTTP: initialize, notifications/initialized, tools/list y tools/call se pueden hacer con curl. Un SDK ayuda con el streaming y con los tipos, no es un requisito.

¿Por qué me devuelve 404 si la clave es válida?

Porque falta la cabecera mcp-session-id. El 404 con mensaje "Invalid or expired Mcp-Session-Id" es una sesión ausente o caducada, no un problema de permisos: repite initialize y usa el id nuevo.

¿Dónde se indica el workspace?

No se indica: se resuelve desde la API key. Una clave puede alcanzar varios workspaces enlazados, y las herramientas que aceptan ámbito lo usan cuando hace falta.

¿La clave se valida al conectar o en la primera herramienta?

Al conectar: durante initialize. Una clave inválida devuelve 401 y una archivada 403 en ese momento, antes de abrir sesión.

¿Qué diferencia hay entre GET y POST en /mcp?

POST envía mensajes JSON-RPC del cliente al servidor. GET abre el stream SSE servidor-cliente de una sesión existente. DELETE cierra la sesión.

¿Cuántas sesiones puedo tener abiertas?

El servidor mantiene sesiones en memoria y las purga por inactividad; no hay un número publicado. Si vas a hacer muchas conexiones cortas, cierra con DELETE al terminar.

Fuentes

• Información de servicio del agente (sin autenticación)
  https://api.ai-tasker.theboomer.dev/agent/service-info
• Manifiesto del servidor MCP
  https://ai-tasker.theboomer.dev/server.json
• Catálogo de herramientas y endpoints
  https://ai-tasker.theboomer.dev/llms-full.txt

Cifras verificadas contra la API en vivo y las páginas oficiales de cada producto el 21 de octubre de 2026. Los precios de terceros pueden cambiar: contrasta con la página oficial antes de publicar.

Guías relacionadas

• Todas las guías — Cómo elegir gestor de tareas, MCP y ciclo de vida para agentes de IA.
• MCP o API HTTP: cuándo usar cada uno — MCP o API HTTP: qué resuelve cada acceso, cuándo usar cada uno y cómo decidir sin duplicar integraciones. Configuración copiable y coste real.
• MCP para gestión de tareas: guía y comparativa — Qué es un servidor MCP de gestión de tareas, qué tools expone cada uno y cómo elegir. Tabla con precios reales de cada servidor.
• Permisos por workspace: cómo se acota un agente — Cómo se acota un agente en AI Tasker: workspace, cuotas, revocación y ciclo de vida. Qué limitan hoy los scopes y qué no.
• Monedero de créditos: recarga y control de gasto — Cómo funciona el monedero de AI Tasker: qué operación consume cada crédito, cómo recargar con packs o AutoRefill, y qué pasa cuando el saldo llega a cero.
• Precios — Precios reales: plan gratuito y unidad facturable de 2,00 €/mes.
• Integración MCP — https://mcp.ai-tasker.theboomer.dev/mcp
• /llms.txt — Contrato legible por máquina.