Custom MCP client

HyperMemory speaks MCP over Streamable HTTP. Any language that can make HTTP POST requests can call the tools.

Wire format

Requests are JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hm_store",
    "arguments": {
      "key": "fact_launch_date",
      "description": "Product launches on 2026-06-01",
      "node_type": "fact",
      "data": {"date": "2026-06-01"}
    }
  }
}

Responses return a result containing a content array with text blocks. The text is JSON of the tool’s response model.

Authentication

Include one of:

• OAuth token: Authorization: Bearer <oauth_token> (see MCP with OAuth)
• API key: Authorization: Bearer hm_YOUR_KEY (see MCP with API key)

Python example

import httpx

class HyperMemoryClient:
    def __init__(self, url: str, api_key: str | None = None):
        self.url = url
        self.headers = {"Content-Type": "application/json"}
        if api_key:
            self.headers["Authorization"] = f"Bearer {api_key}"
        self._id = 0

    def call(self, tool: str, args: dict) -> dict:
        self._id += 1
        r = httpx.post(
            self.url,
            json={
                "jsonrpc": "2.0",
                "id": self._id,
                "method": "tools/call",
                "params": {"name": tool, "arguments": args},
            },
            headers=self.headers,
            timeout=30.0,
        )
        r.raise_for_status()
        data = r.json()
        if "error" in data:
            raise Exception(data["error"].get("message", "MCP error"))
        return data.get("result", {})

    def list_tools(self) -> list:
        self._id += 1
        r = httpx.post(
            self.url,
            json={"jsonrpc": "2.0", "id": self._id, "method": "tools/list", "params": {}},
            headers=self.headers,
            timeout=10.0,
        )
        return r.json().get("result", [])

JavaScript example

async function callMCP(url, apiKey, tool, args) {
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: { name: tool, arguments: args },
    }),
  });
  const data = await res.json();
  if (data.error) throw new Error(data.error.message);
  return data.result;
}

List available tools

Call tools/list to discover all hm_* tools at runtime:

curl -X POST https://api.hypermemory.io/mcp \
  -H "Authorization: Bearer hm_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

REST API

For non-MCP integrations, a REST API is also available. See REST API Endpoints for the full endpoint list.

See API Reference for the full tool catalog with parameter types.