Request Handling

ZenZ APIs leverage the Model Context Protocol (MCP) for request management, providing a unified interface for all ecosystem interactions. This integration enables standardized communication patterns across Network, Identity, Storage, Compute, and Trust components, ensuring consistent and intelligent request handling throughout the platform.

Check out here to learn more about how and why ZenZ explores MCP.

Request

Base URL

For Sandbox

https://sandbox-bootnode1.zenz.tech

Protocol Version

MCP protocol version: 2025-11-25

Payload


/**
 * All requests follow below standardized format for payload
 */
{
  method: ZMethodType;                     
  params: MethodParams;               /** Method-specific parameters */
  _meta?: RequestMetadata;            /** Optional request metadata */
}

The param method in ZRequest defines the specific action to perform, such as tools/call for execution, resources/read for data retrieval, or */list for discovery. It acts as an instruction to the MCP server indicating how to process the accompanying params.

Method types


enum ZMethodType {
  RESOURCES_LIST = 'resources/list',    /** Resource listing operations */
  RESOURCES_READ = 'resources/read',    /** Resource reading operations */
  RESOURCES_WRITE = 'resources/write',  /** Resource writing operations */
  TOOLS_LIST = 'tools/list',            /** Tool listing operations */
  TOOLS_CALL = 'tools/call',            /** Tool execution operations */
}

Method Params


interface MethodParams {
  method: string, 
  arguments: any // Object
}

The param method in MethodParams is the actual method for different set of services among identity, storage, DB and ledger in ZenZ Ecosystem

RequestMetadata


interface RequestMetadata {
  requestId?: string;                /** Unique request identifier for tracing */
  timestamp?: string;                /** Timestamp when request was initiated */
  tenantId?: string;                 /** The User ID making the request */
  appId?: string;                    /** Application ID making the request */
  authorization?: string;            /** the zat token
  provider?: string;                 /** the resource provider you are accessing **/
}

Sample Request Payload


{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
      "name": "execute_raw_query",
      "arguments": {
          "tenant_id": "000000009abe0feaa2fc0d06cbf102ebd8cf7a71a1e3aa0291cad87100000000",
          "query": "CREATE TABLE IF NOT EXISTS inventory (id SERIAL PRIMARY KEY, sku VARCHAR(50) UNIQUE NOT NULL, name TEXT NOT NULL, quantity INTEGER DEFAULT 0, category VARCHAR(100), price DECIMAL(12,2), is_active BOOLEAN DEFAULT true, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP);"
      },
      "_meta": {
          "provider": "postgres"
      }
  }
}

Response

Follows standards same as MCP

Success Response


{
    "result": {
        "content": [
            {
                "type": "text",
                "text": "{\n  \"resourceURI\": \"zttp-storage://ipfs:12D3KooWFbkK4hJsZTxgUNa4A12qaU5gvSYFNCSSH1o7P1n1YKL4/Qmbsch5zWd7fbEYqdSt3iLUzgFoYNRTDtwidAisdDuo35q\",\n  \"hash\": \"Qmbsch5zWd7fbEYqdSt3iLUzgFoYNRTDtwidAisdDuo35q\",\n  \"status\": \"success\"\n}"
            }
        ]
    },
    "jsonrpc": "2.0",
    "id": "1"
}

Error Response


{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: API rate limit exceeded. Please try again in 30 seconds."
      }
    ],
    "isError": true
  }
}