Custom MCP client

HyperMemory’s MCP server speaks Streamable HTTP in stateless JSON mode: every call is one HTTP POST carrying a JSON-RPC 2.0 message, and the answer comes back as JSON. There’s no session to open, so any language that can make HTTP requests can call it.

If you can use an MCP SDK, do — point it at https://api.hypermemory.io/mcp. If you don’t need MCP at all, the REST API is simpler.

Wire format

POST /mcp HTTP/1.1
Host: api.hypermemory.io
Authorization: Bearer hm_YOUR_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hm_store",
    "arguments": {
      "key": "fact_launch_date",
      "node_type": "fact",
      "description": "Product launches on 2026-11-02 after the security review sign-off."
    }
  }
}

The result holds the tool’s answer twice: as JSON in structuredContent, and as a short summary in content[0].text. Pass "response_format": "text" in arguments to get the full JSON as text instead, or "both" for both.

A tool error is a normal result with isError: true; its structuredContent has error, error_code and retryable. See Errors & limits.

Authentication

Send one of these as Authorization: Bearer …:

• an API key (hm_…) — see MCP with an API key;
• an OAuth access token — see OAuth.

Python

import os
import uuid
import httpx


class HyperMemory:
    def __init__(self, api_key: str | None = None,
                 url: str = "https://api.hypermemory.io/mcp"):
        self.url = url
        self.client = httpx.Client(timeout=30, headers={
            "Authorization": f"Bearer {api_key or os.environ['HYPERMEMORY_API_KEY']}",
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
        })

    def _rpc(self, method: str, params: dict, request_id: str | None = None) -> dict:
        headers = {"X-Request-ID": request_id} if request_id else {}
        r = self.client.post(self.url, headers=headers, json={
            "jsonrpc": "2.0", "id": 1, "method": method, "params": params,
        })
        r.raise_for_status()
        body = r.json()
        if "error" in body:
            raise RuntimeError(body["error"]["message"])
        return body["result"]

    def list_tools(self) -> list[dict]:
        return self._rpc("tools/list", {})["tools"]

    def call(self, tool: str, **arguments) -> dict:
        # One request id per logical call: reuse it on retry so writes apply once.
        result = self._rpc("tools/call", {"name": tool, "arguments": arguments},
                           request_id=str(uuid.uuid4()))
        if result.get("isError"):
            raise RuntimeError(result["structuredContent"])
        return result["structuredContent"]


hm = HyperMemory()
hm.call("hm_store",
        key="fact_launch_date", node_type="fact",
        description="Product launches on 2026-11-02 after the security review sign-off.")
for hit in hm.call("hm_recall", query="when do we launch")["results"]:
    print(hit["key"], hit["score"])

JavaScript

const URL = "https://api.hypermemory.io/mcp";

export async function callTool(name, args, apiKey = process.env.HYPERMEMORY_API_KEY) {
  const res = await fetch(URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      Accept: "application/json, text/event-stream",
      "X-Request-ID": crypto.randomUUID(),
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name, arguments: args },
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  if (body.result.isError) throw new Error(JSON.stringify(body.result.structuredContent));
  return body.result.structuredContent;
}

const { results } = await callTool("hm_recall", { query: "when do we launch" });

Discover tools

tools/list returns all 18 tools with their input schemas — useful for generating function definitions for other model providers:

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

Give your agent the protocol

Tools are only half of it. Fetch the HyperMemory skill with hm_skill (variant: "general") and put it in your agent’s system prompt: it tells the model to recall before replying, write good nodes, and report tokens.