Ria: MCP knowledge server and cost accounting - design reference

Researched 2026-10-12. Spec version cited: MCP 2025-11-25. Anything not confirmed on a primary page is marked [unverified].

Part A. MCP server that serves Ria's knowledge

A1. Transport: streamable HTTP, one endpoint

• The spec defines two standard transports: stdio and Streamable HTTP. Streamable HTTP replaces the old HTTP+SSE transport from 2024-11-05. Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
• One MCP endpoint path (e.g. https://trust.arnao.ai/mcp) must accept POST and GET. Clients POST every JSON-RPC message with Accept: application/json, text/event-stream; the server replies with JSON or opens an SSE stream. GET is optional (server-to-client stream) and may return 405.
• Servers MUST validate the Origin header (403 on invalid, to stop DNS rebinding); bind to localhost when local; SHOULD authenticate every connection.
• Sessions are optional: MCP-Session-Id header; client must send MCP-Protocol-Version. For a read-mostly knowledge server, run stateless (no session IDs) so any worker can answer. FastMCP: stateless_http=True or env FASTMCP_STATELESS_HTTP=true (FastMCP HTTP deployment).
• Legacy /sse endpoints exist only for old clients (DeepWiki says its SSE endpoint is being phased out: https://docs.devin.ai/work-with-devin/deepwiki-mcp). Do not build SSE-only.
• Local-only consumers on the Mini can use stdio; the multi-app case needs HTTP.

A2. Auth options (pick by consumer)

The authorization section is OPTIONAL in the spec, and for HTTP transports it says implementations SHOULD follow it. Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization

FastMCP supports bearer verifiers (StaticTokenVerifier for dev/test, per the docs) and OAuth providers (GitHub etc.), with a production OAuth proxy needing an explicit jwt_signing_key and encrypted persistent storage (docs). For a production bearer scheme, write a small custom TokenVerifier that checks hashed tokens against a table instead of using the dev verifier. API details beyond the doc summary: read the FastMCP auth docs before coding [unverified].

Recommendation: Streamable HTTP, stateless, single /mcp endpoint, bearer token per consuming app now; add OAuth 2.1 resource-server metadata later if claude.ai/third-party connectors are wanted. Put it behind Cloudflare/Tailscale Funnel or an arnao.ai host with TLS.

A3. Tool, resource, pagination conventions

From the tools spec (https://modelcontextprotocol.io/specification/2025-11-25/server/tools):

• Tool names: 1-128 chars, case-sensitive, only A-Za-z0-9_-., unique per server. Dots are allowed, so namespace: incidents.search, incidents.get.
• Provide title, description, inputSchema (JSON Schema 2020-12 default), and an outputSchema plus structuredContent; also return the JSON as a text block for compatibility.
• Input validation failures should be returned as isError: true results with an actionable message so the model can self-correct; protocol errors are for malformed requests.
• Tools may return resource_link items instead of big payloads; link to resources and let the client fetch.
• Servers MUST validate inputs, rate-limit, and sanitize outputs. Scraped Moltbook/web text in results is untrusted and may carry prompt injection: mark it clearly (e.g. untrusted_content: true) and strip instructions-like markup.
• Annotations (such as read-only hints) exist but clients must treat them as untrusted unless from trusted servers; do not rely on them for security.

Pagination (https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination): opaque cursor / nextCursor; server chooses page size; applies to resources/list, resources/templates/list, prompts/list, tools/list; bad cursor returns -32602. For your own data tools (which are not covered by that mechanism) copy the same convention: limit (cap 50), cursor in, next_cursor out, base64 of (sort_key, id); results sorted by a stable key such as (published_at DESC, id).

Proposed surface

Tools (read-only unless noted):

• incidents.search(query, since?, severity?, tags?, limit?, cursor?), incidents.get(id), incidents.timeline(entity_id)
• briefs.latest(), briefs.get(date), briefs.search(query, limit?, cursor?)
• sources.search(query), sources.get(id) (source index: URL, type, reliability grade, last fetched)
• entities.get(slug), entities.search(query) (labs, people, models, orgs)
• models.lineup(provider?) (model lineup with release dates; every row cites a URL)
• ria.submit_lead(url, note) (the only write tool; queue for review, never direct write to corpus)

Resources (URI templates, so clients can attach context):

• ria://brief/{yyyy-mm-dd}, ria://incident/{id}, ria://entity/{slug}, ria://source/{id}, ria://models/current
• resources/subscribe on ria://brief/latest is a good fit for push when the daily brief lands.

Prompts: ria.explain_incident, ria.weekly_rollup.

A4. Caching

• Briefs and incident records are immutable once published: serve with ETag/Cache-Control: max-age at the HTTP edge for resource reads; version records (updated_at, revision) rather than mutating.
• tools/list is stable; emit listChanged only when the surface changes.
• Server-side: SQLite (WAL) or Postgres with FTS5/pgvector; cache search results by normalized query for minutes; precompute the latest brief and model lineup at write time.
• Stateless mode lets multiple workers share one DB with no sticky sessions.

A5. Knowledge-base MCP servers in the wild (to study)

• DeepWiki: tools read_wiki_structure, read_wiki_contents, ask_question; https://mcp.deepwiki.com/mcp; no auth for public repos. https://docs.devin.ai/work-with-devin/deepwiki-mcp
• Context7: https://mcp.context7.com/mcp Streamable HTTP with OAuth, API key for higher limits. https://www.mintlify.com/upstash/context7/mcp/overview
• Reference memory server (knowledge graph in JSONL; search_nodes, read_graph, open_nodes): https://github.com/modelcontextprotocol/servers
• arXiv MCP: https://github.com/blazickjp/arxiv-mcp-server

A6. SDK choice

• FastMCP (Python, Apache-2.0, v4.1.0 on 08 Oct 2026): https://github.com/PrefectHQ/fastmcp . Mount in FastAPI via Mount(), pass mcp_app.lifespan to the parent app or sessions will not initialise (docs).
• Official Python SDK (MIT, v2.3.0 on 02 Oct 2026): https://github.com/modelcontextprotocol/python-sdk . Fine if you want zero extra deps. Its README page I fetched did not cover auth classes; see https://py.sdk.modelcontextprotocol.io/ [unverified].
• TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk .
• Ria is on Python (Mini, Ollama), so FastMCP is the default.

---

Part B. Cost accounting for an autonomous agent

B1. Where each provider reports cost

Anthropic API

• Per response: the usage object (input, output, cache_creation_input_tokens, cache_read_input_tokens). Compute USD yourself from a price table. Pricing: https://platform.claude.com/docs/en/about-claude/pricing
• Authoritative after the fact: Usage and Cost Admin API. Docs: https://platform.claude.com/docs/en/manage-claude/usage-cost-api
• GET https://api.anthropic.com/v1/organizations/usage_report/messages with starting_at, ending_at, bucket_width (1m/1h/1d), group_by[] (model, workspace, api key, service tier, etc.), filters; max buckets 1,440 / 168 / 31.
• GET https://api.anthropic.com/v1/organizations/cost_report daily buckets only, USD as decimal strings in cents, group by workspace_id / description. Priority Tier costs are excluded from the cost endpoint; use the usage endpoint.
• Auth: Admin API key (sk-ant-admin01-...) or equivalent admin credential; workspace API keys do not work. Unavailable for individual accounts; needs an Organization set up in Console. Header anthropic-version: 2023-06-01.
• Freshness: typically within 5 minutes; poll at most about once a minute sustained. Pagination via has_more / next_page.
• Tip: give Ria its own workspace and API key so workspace_id / api_key_id isolates its spend (default workspace shows null).
• Caveat for Byron: if Ria runs through a Claude subscription (Claude Code login) rather than an API key, none of this applies; spend is not itemised in USD.

OpenRouter

• In-response accounting: usage is included automatically in every response (final SSE chunk when streaming): prompt_tokens, completion_tokens, total_tokens, cost (credits charged), cost_details.upstream_inference_cost, completion_tokens_details.reasoning_tokens, prompt_tokens_details.cached_tokens/cache_write_tokens. The old usage: {include: true} flag is deprecated and has no effect. https://openrouter.ai/docs/guides/guides/usage-accounting
• After the fact: GET https://openrouter.ai/api/v1/generation?id=gen-... (Bearer key) returns total_cost, usage, upstream_inference_cost, cache_discount, normalized tokens_prompt/completion and native token counts, latency, generation_time, provider_name, model, request_id, is_byok, cancelled. https://openrouter.ai/docs/api-reference/get-a-generation . Per the usage-accounting page, upstream cost from this endpoint is only populated for BYOK requests.

Local Ollama

• Ollama responses include token counts (prompt_eval_count, eval_count) and durations; I did not re-verify field names against current docs this session [unverified]: check https://github.com/ollama/ollama/blob/main/docs/api.md . USD is $0 marginal; record tokens and wall time, and optionally an electricity estimate (watts x seconds) for honest comparison.

LiteLLM as a single meter

• Gateway with per-key budgets and spend logs across all three providers: https://github.com/BerriAI/litellm (v1.105.0). Treat its dollar numbers as estimates and reconcile weekly against the Anthropic cost report and OpenRouter activity page.

B2. Claude Code headless (claude -p)

Docs: https://code.claude.com/docs/en/headless and https://code.claude.com/docs/en/agent-sdk/cost-tracking

• --output-format json returns a JSON object whose text is in result, plus session_id, usage, and total_cost_usd with a per-model breakdown (modelUsage: costUSD, input/output/cache tokens). I did not see the full field list on the headless page (e.g. duration_ms, num_turns) so verify those against a real run [unverified].
• --output-format stream-json (with --verbose) ends with a result message carrying final text, cost and session metadata. --bare is recommended for scripted runs.
• Caveats from the docs (important for a ledger):
• total_cost_usd is a client-side estimate from a bundled price table, not billing data; use the Usage and Cost API for authoritative figures and do not make financial decisions from it.
• When continuing with --continue or --resume, the result reports the whole session total, including earlier runs. Do not sum across resumed calls; take the latest or compute deltas (since v2.1.277 per docs).
• usage excludes subagent tokens; total_cost_usd and modelUsage include them. Use modelUsage for token accounting.
• Error results also carry cost; on error_max_budget_usd, usage omits the response that crossed the cap while total_cost_usd includes it. After a process crash the cost fields may be zeroed.
• A --max-budget-usd CLI flag exists (the headless page references it); the Agent SDK equivalent max_budget_usd counts only the call's own spend. Use it as a per-run backstop, not the daily cap.
• Exit code 143 on SIGTERM and no result recorded for the in-flight turn: your wrapper must still write a ledger row (cost unknown) on non-zero exit.

B3. Ledger schema (SQLite)

CREATE TABLE ledger (
  id            INTEGER PRIMARY KEY,
  run_id        TEXT NOT NULL,         -- uuid per scheduled run
  parent_run_id TEXT,                  -- for subtasks / retries
  task          TEXT NOT NULL,         -- 'daily_brief','moltbook_probe','ingest_feed',...
  provider      TEXT NOT NULL,         -- 'anthropic' | 'openrouter' | 'ollama'
  model         TEXT NOT NULL,
  input_tokens  INTEGER NOT NULL DEFAULT 0,
  output_tokens INTEGER NOT NULL DEFAULT 0,
  cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
  cache_write_tokens  INTEGER NOT NULL DEFAULT 0,
  usd           REAL NOT NULL,         -- estimate at write time
  usd_source    TEXT NOT NULL,         -- 'claude_cli_estimate'|'openrouter_cost'|'price_table'|'zero_local'
  wall_ms       INTEGER NOT NULL,
  status        TEXT NOT NULL,         -- ok|error|killed|capped
  external_id   TEXT,                  -- claude session_id / openrouter gen-id
  reconciled_usd REAL,                 -- filled by nightly reconcile from admin APIs
  started_at    TEXT NOT NULL,         -- UTC ISO8601
  UNIQUE(provider, external_id)
);
CREATE INDEX ledger_day ON ledger(substr(started_at,1,10));

Write one row per model call (or per claude -p run using modelUsage rows), including failures. A nightly job fills reconciled_usd from the Anthropic cost report and OpenRouter, and alerts when drift exceeds e.g. 15%.

B4. Daily cap and kill switch pattern

1. Pre-flight gate (before every model call and before each claude -p): SELECT SUM(usd) FROM ledger WHERE day=today plus an in-flight reservation (worst-case estimate for this call). If spent + reservation > DAILY_CAP_USD (say 80% soft, 100% hard), refuse and log status=capped. Mirrors the "blocking guardrail runs before spend" idea in the OpenAI Agents SDK guardrails (docs).
2. Per-run cap: pass --max-budget-usd to claude -p, set provider max_tokens, and a wall-clock timeout; budget per task type, not just per day.
3. Kill switch file: a path such as ~/ria/KILL checked by the gate and by a Claude Code PreToolUse hook (hooks run deterministically and can block tool calls: https://code.claude.com/docs/en/hooks-guide). If present, every run exits immediately. Also expose it as an MCP admin tool, not on the public surface.
4. Circuit breaker: if hourly spend exceeds N times the trailing average, or 3 consecutive runs error, auto-create the kill file and alert Byron (his usual Signal/slog path).
5. Provider-side backstops: a separate Anthropic workspace with its own spend limit if available in Console, OpenRouter key credit limit, and LiteLLM per-key max_budget. These catch bugs in your own ledger. Confirm the exact settings in each console [unverified].
6. Cheap-first cascade: screen with Ollama or Haiku-class, escalate only top items to a large model (the pattern NewsUpdate uses: gpt-4o-mini screening, gpt-4o analysis).
7. Never trust a single estimate: the Claude CLI total is client-side; reconcile.

B5. Caveats

• Anthropic admin APIs require an organization account, which may not match how Byron currently authenticates Claude Code on the Mini.
• I did not verify current model prices; fetch the pricing page when building the price table.