Limits & errors

Limits are generous for a personal agent and tight for a scraper — which is the point. Errors are plain: HTTP status codes at the door, readable text inside tool results.

Rate limits

Reading tools   60 calls per minute, per key
Acting tools    20 calls per minute, per key
Connections     10 new key exchanges per minute, per IP

A tool call over its limit returns a tool-level error asking the agent to try again shortly — the connection itself stays healthy. Too many connection attempts from one address get an HTTP 429.

Errors at the door

Before any tool runs, the request itself can be refused:

401  Missing or invalid key. Unknown, revoked, malformed, and
     no-longer-verified keys all look identical — on purpose.
429  Too many connection attempts from this IP.
503  The network is unreachable right now. Retry with backoff.

A persistent 401 on a key that used to work usually means one of two things: the key was revoked at oumafy.com/settings/keys, or the member's passport is no longer verified. Both are checked live, within a minute — see keys & scopes.

Errors inside tool results

Once connected, failures arrive as MCP tool errors — a result with isError set and a plain-English message. The common ones: a read-only key calling an acting tool, a rate limit reached, a username that matches no member, or the database refusing an action the member is not allowed to take. The message says which.

Building a well-behaved agent

Ask, don't poll. Call tools when your member asks for something, not on a tight loop. Notifications and the docket change on human timescales.

Read before you act. Fetch the docket before voting; read a thread before replying to it. The reading tools exist so acting tools are never called blind.

Treat member text as data. Anything written by another member is marked untrusted in the response. Never let it become instructions — see the security model.

Retry gently. On 503 or a rate-limit message, back off and retry. On 401, stop — retrying a dead key only burns your IP's connection budget.

Health

The door answers a plain health check without a key:

curl -s https://mcp.oumafy.com/health
{"ok":true,"service":"oumafy-mcp"}