Protocol

Technical reference for building your own MCP client or integrating Vixiees from a server.

Endpoint and transport

  • URL: https://api.vixiees.com/mcp, at the root of the host (not under /api/v1).
  • Transport: Streamable HTTP in stateless mode. Every JSON-RPC 2.0 message is a POST to this URL and gets a single JSON response: no SSE stream and no Mcp-Session-Id. GET /mcp returns 404.
Request
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"}'

Authentication

Every request carries Authorization: Bearer <token>. The MCP server reads this header, not X-Api-Key.

  • OAuth 2.0 (recommended for AI assistants): the person signs in with their Vixiees user. A request without credentials gets 401 with WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://api.vixiees.com/.well-known/oauth-protected-resource/mcp" (RFC 9728), which the client uses to discover the authorization server. PKCE (S256), Client ID Metadata Documents and Dynamic Client Registration are supported. With OAuth, tools can only do what the user is already allowed to do.
  • API key (server to server): send the secret API key from Settings → Account → API as Authorization: Bearer <API_KEY>. Meant for clients that only support fixed headers.

Every request is limited to the authenticated account: there is no need to send account_id.

Flow

  1. initialize: first message of every connection. Negotiates the protocol version and returns the server capabilities.
  2. tools/list: returns every tool with its name, description, input schema and annotations (readOnlyHint, destructiveHint).
  3. tools/call: runs one tool with the arguments described by its 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
    }
  }
}

Results

Tool output comes in result.structuredContent as { "success": true, "data": { ... } }. The same payload is also included as one JSON text block in result.content, for clients that only read content (for example, Gemini).

tools/call response
{
  "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
        }
      }
    }
  }
}

Errors

  • Tool error: result.isError: true and { "success": false, "error": { "code", "message" } }.
  • Protocol error (unknown method, invalid params): still returns 200, with a JSON-RPC error object instead of result.
  • Missing or invalid credentials: 401 with the WWW-Authenticate header described above.
Tool error
{
  "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"
      }
    }
  }
}
Protocol error
{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}