Protocolo

Referencia técnica para quien construye su propio cliente MCP o integra Vixiees desde un servidor.

Endpoint y transporte

  • URL: https://api.vixiees.com/mcp, en la raíz del host (no bajo /api/v1).
  • Transporte: Streamable HTTP en modo sin estado. Cada mensaje JSON-RPC 2.0 es un POST a esta URL y recibe una única respuesta JSON: sin stream SSE ni Mcp-Session-Id. GET /mcp devuelve 404.
Petición
curl -X POST 'https://api.vixiees.com/mcp' \
  -H 'Authorization: Bearer <ACCESS_TOKEN_OR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Autenticación

Todas las peticiones llevan Authorization: Bearer <token>. El servidor MCP lee esa cabecera, no X-Api-Key.

  • OAuth 2.0 (recomendado para asistentes de IA): el usuario inicia sesión con su usuario de Vixiees. Una petición sin credenciales recibe 401 con WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://api.vixiees.com/.well-known/oauth-protected-resource/mcp" (RFC 9728), que el cliente usa para descubrir el servidor de autorización. Se admiten PKCE (S256), Client ID Metadata Documents y Dynamic Client Registration. Con OAuth, las herramientas solo pueden hacer lo que el usuario ya tiene permitido.
  • API key (servidor a servidor): envía la API key secreta de Settings → Account → API como Authorization: Bearer <API_KEY>. Pensada para clientes que solo admiten cabeceras fijas.

Cada petición se limita a la cuenta autenticada: no hace falta enviar account_id.

Flujo

  1. initialize: primer mensaje de cada conexión. Negocia la versión del protocolo y devuelve las capacidades del servidor.
  2. tools/list: devuelve cada herramienta con su nombre, descripción, esquema de entrada y anotaciones (readOnlyHint, destructiveHint).
  3. tools/call: ejecuta una herramienta con los argumentos que describe su inputSchema.
initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}
tools/list
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
tools/call
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_contacts_tool",
    "arguments": {
      "word": "maria",
      "limit": 10
    }
  }
}

Resultados

El resultado de una herramienta llega en result.structuredContent como { "success": true, "data": { ... } }. El mismo contenido se incluye también como un bloque de texto JSON en result.content, para los clientes que solo leen content (por ejemplo, Gemini).

Respuesta de tools/call
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "{\"success\":true,\"data\":{\"contacts\":[{\"id\":\"665f1c2e8b3a4d0012345678\",\"name\":\"María García\",\"email\":\"maria@example.com\"}],\"pagination\":{\"page\":1,\"per_page\":10,\"total_count\":1,\"total_pages\":1}}}"
      }
    ],
    "structuredContent": {
      "success": true,
      "data": {
        "contacts": [
          {
            "id": "665f1c2e8b3a4d0012345678",
            "name": "María García",
            "email": "maria@example.com"
          }
        ],
        "pagination": {
          "page": 1,
          "per_page": 10,
          "total_count": 1,
          "total_pages": 1
        }
      }
    }
  }
}

Errores

  • Error de la herramienta: result.isError: true y { "success": false, "error": { "code", "message" } }.
  • Error del protocolo (método desconocido, parámetros no válidos): también responde 200, con un objeto error JSON-RPC en lugar de result.
  • Sin credenciales o credenciales no válidas: 401 con la cabecera WWW-Authenticate descrita arriba.
Error de la herramienta
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "{\"success\":false,\"error\":{\"code\":\"NOT_FOUND\",\"message\":\"Contact not found\"}}"
      }
    ],
    "structuredContent": {
      "success": false,
      "error": {
        "code": "NOT_FOUND",
        "message": "Contact not found"
      }
    }
  }
}
Error del protocolo
{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}