All tool calls are JSON-RPC 2.0 over HTTPS POST to /mcp:
POST /mcp HTTP/1.1
Authorization: Bearer <OAuth-2.1-access-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": {...}.
A 64-bit integer (Postgres BIGSERIAL). Stable for the row’s
lifetime; never reused after a hard-delete.
ISO 8601 with timezone, e.g. "2026-05-17T14:00:00Z".
Lowercase short strings, alphanumeric plus hyphen. See Tag normalization.
Never returned in tool output; an implementation detail of the similarity search.
Every request must carry Authorization: Bearer JWT,
where JWT is an OAuth 2.1 access token issued by OwnSona’s
embedded authorization server. The resource-server side validates
the token’s signature against the AS’s JWKS, plus the iss,
aud, exp, and (if configured) required scopes.
Missing, malformed, expired, or wrong-signature tokens return HTTP
401 with an RFC 6750 / RFC 9728 WWW-Authenticate header
naming the resource-metadata document at
/.well-known/oauth-protected-resource. MCP clients use that
header to (re-)discover the AS and refresh their token.
MCP clients normally obtain a token by the auth-code + PKCE flow:
the client discovers the AS via the well-known metadata documents,
registers itself dynamically at /oauth/register (RFC 7591),
sends the user to /oauth/authorize (where they log in with
OWNSONA_LOGIN_USERNAME / OWNSONA_LOGIN_PASSWORD and
click Allow), and exchanges the resulting code at
/oauth/token for an access token and refresh token. Refresh
tokens are rotated on each use, with stolen-token detection per
RFC 6749bis.