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
POSTto this URL and gets a single JSON response: no SSE stream and noMcp-Session-Id.GET /mcpreturns404.
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
401withWWW-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
initialize: first message of every connection. Negotiates the protocol version and returns the server capabilities.tools/list: returns every tool with its name, description, input schema and annotations (readOnlyHint,destructiveHint).tools/call: runs one tool with the arguments described by itsinputSchema.
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: trueand{ "success": false, "error": { "code", "message" } }. - Protocol error (unknown method, invalid params): still returns
200, with a JSON-RPCerrorobject instead ofresult. - Missing or invalid credentials:
401with theWWW-Authenticateheader 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"
}
}