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
POSTa esta URL y recibe una única respuesta JSON: sin stream SSE niMcp-Session-Id.GET /mcpdevuelve404.
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
401conWWW-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
initialize: primer mensaje de cada conexión. Negocia la versión del protocolo y devuelve las capacidades del servidor.tools/list: devuelve cada herramienta con su nombre, descripción, esquema de entrada y anotaciones (readOnlyHint,destructiveHint).tools/call: ejecuta una herramienta con los argumentos que describe suinputSchema.
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: truey{ "success": false, "error": { "code", "message" } }. - Error del protocolo (método desconocido, parámetros no válidos): también responde
200, con un objetoerrorJSON-RPC en lugar deresult. - Sin credenciales o credenciales no válidas:
401con la cabeceraWWW-Authenticatedescrita 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"
}
}