LLMRing Server

GitHub: https://github.com/juanre/llmring-server

Self-hostable backend that adds optional capabilities: signed receipts, usage logging/stats, conversation persistence, MCP tool/resource/prompt management, and a read-only proxy to the public registry. No alias storage or synchronization - aliases remain local to each codebase’s lockfile. Dual‑mode: standalone service or embedded as a library (used by llmring-api).

Quick Start

uv run llmring-server --reload

Default: http://localhost:8000 with Swagger at /docs.

Authentication

• Project-scoped via X-API-Key header (api_key_id as VARCHAR)
• No user management in this service - aliases are local to each codebase’s lockfile

Endpoints (selected)

Public:

• GET / – service info
• GET /health – DB health
• GET /registry or /registry.json – aggregated registry
• GET /receipts/public-key.pem – current public key
• GET /receipts/public-keys.json – list of active/rotated public keys

Examples

curl http://localhost:8000/

curl http://localhost:8000/registry.json

Project-scoped (require X-API-Key):

• Usage: POST /api/v1/log, GET /api/v1/stats
• Receipts: POST /api/v1/receipts (store signed), GET /api/v1/receipts/{id}, POST /api/v1/receipts/issue
• Conversations: POST /conversations, GET /conversations, GET /conversations/{id}, POST /conversations/{id}/messages/batch
• MCP Servers: POST /api/v1/mcp/servers, GET /api/v1/mcp/servers, POST /api/v1/mcp/servers/{id}/refresh
• MCP Tools: GET /api/v1/mcp/tools, POST /api/v1/mcp/tools/{id}/execute, GET /api/v1/mcp/tools/{id}/history
• MCP Resources: GET /api/v1/mcp/resources, GET /api/v1/mcp/resources/{id}/content
• MCP Prompts: GET /api/v1/mcp/prompts, POST /api/v1/mcp/prompts/{id}/render

Usage API

• POST /api/v1/log body { provider, model, input_tokens, output_tokens, cached_input_tokens?, alias?, profile?, cost?, latency_ms?, origin?, id_at_origin?, metadata? } → { log_id, cost, timestamp }
• GET /api/v1/stats?start_date=&end_date=&group_by=day → { summary, by_day[], by_model{}, by_origin{} }

Receipts API

• POST /api/v1/receipts body { receipt: {...} } → { receipt_id, status: "verified" }
• GET /api/v1/receipts/{id} → full receipt object
• POST /api/v1/receipts/issue body is an unsigned receipt → signed receipt (requires server signing key)

Configuration (env)

• LLMRING_DATABASE_URL (required)
• LLMRING_DATABASE_SCHEMA (default: llmring)
• LLMRING_REDIS_URL (optional, caching)
• LLMRING_REGISTRY_BASE_URL (default: https://llmring.github.io/registry/)
• LLMRING_RECEIPTS_PRIVATE_KEY_B64, LLMRING_RECEIPTS_PUBLIC_KEY_B64, LLMRING_RECEIPTS_KEY_ID

Dual‑mode

• Standalone: manages its own DB connections and migrations
• Library: use create_app(db_manager=..., standalone=False, run_migrations=...) with an external pool

App factory:

create_app(
  db_manager: AsyncDatabaseManager | None = None,
  run_migrations: bool = True,
  schema: str | None = None,
  settings: Settings | None = None,
  standalone: bool = True,
  include_meta_routes: bool = True,
) -> FastAPI

Receipts

• Ed25519 signature over RFC 8785 JCS
• Canonical receipts are stored/verified by the server

Receipt fields (subset): id, timestamp, model, alias, profile, lock_digest, key_id, tokens { input, output, cached_input }, cost { amount, calculation }, signature.

MCP Integration

The server provides full MCP (Model Context Protocol) persistence:

MCP Database Schema

• servers - MCP server registry (name, URL, transport, capabilities)
• tools - Available tools with schemas
• resources - Accessible resources (files, URLs, etc.)
• prompts - Reusable prompt templates
• tool_executions - Execution history with inputs/outputs

All MCP operations are project-scoped via the X-API-Key header.

Security Checklist

• Set explicit CORS origins in production
• Serve behind TLS
• Treat X-API-Key as a secret (api_key_id)
• Configure receipts keys to enable verification/issuance
• MCP resources are isolated per project

Links

• GitHub: https://github.com/juanre/llmring-server