General tool conventions (OwnSona Manual)

Next: The remember tool, Up: MCP Tools [Contents][Index]

5.1 General tool conventions ¶

All tool calls are JSON-RPC 2.0 over HTTPS POST to /mcp:

POST /mcp HTTP/1.1
Authorization: Bearer <OWNSONA_API_TOKEN>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool-name>",
    "arguments": { ... }
  }
}

The server returns a JSON-RPC response whose result.content[0].text field holds the tool’s structured payload as a JSON string. Every successful payload begins with "ok": true; every error payload begins with "ok": false, "error": {...}.

Common types
Authentication

5.1.1 Common types ¶

Memory ID: A 64-bit integer (Postgres BIGSERIAL). Stable for the row’s lifetime; never reused after a hard-delete.
Timestamps: ISO 8601 with timezone, e.g. "2026-05-17T14:00:00Z".
Tags: Lowercase short strings, alphanumeric plus hyphen. See Tag normalization.
Vectors: Never returned in tool output; an implementation detail of the similarity search.

5.1.2 Authentication ¶

Every request must carry Authorization: Bearer <token>. The token is compared in constant time against OWNSONA_API_TOKEN from application.ini. Missing or wrong token returns HTTP 401 with AUTH_FAILED.