LLMRing Server

llms.txt

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/
{ "service": "llmring-server", "version": "0.1.0", "status": "operational", "timestamp": "2024-01-15T10:30:45.123Z", "endpoints": { "health": "/health", "registry": "/registry", "api": "/api/v1", "docs": "/docs" } }
curl http://localhost:8000/registry.json
{ "version": "1.0", "generated": "2024-01-15T10:30:45.123Z", "providers": { "openai": { "version": 142, "models": { "gpt-4": { "name": "gpt-4", "max_input_tokens": 8192, "max_output_tokens": 4096, "dollars_per_million_input_tokens": 30.0, "dollars_per_million_output_tokens": 60.0 }, "gpt-4o-mini": { "name": "gpt-4o-mini", "max_input_tokens": 128000, "max_output_tokens": 16384, "dollars_per_million_input_tokens": 0.15, "dollars_per_million_output_tokens": 0.6 } } }, "anthropic": { "version": 89, "models": { "claude-3-haiku": { "name": "claude-3-haiku-20240307", "max_input_tokens": 200000, "max_output_tokens": 4096, "dollars_per_million_input_tokens": 0.25, "dollars_per_million_output_tokens": 1.25 }, "claude-3-opus": { "name": "claude-3-opus-20240229", "max_input_tokens": 200000, "max_output_tokens": 4096, "dollars_per_million_input_tokens": 15.0, "dollars_per_million_output_tokens": 75.0 } } } } }

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, prompt_tokens, completion_tokens, reasoning_tokens?, cache_read_input_tokens?, cache_creation_5m_tokens?, cache_creation_1h_tokens?, cache_creation_input_tokens?, alias?, profile?, cost?, cost_breakdown?, latency_ms?, origin?, id_at_origin?, metadata? } → { log_id, cost, cost_breakdown, 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, reasoning, cache_read, cache_write_5m, cache_write_1h }, cost { amount, breakdown { input, cache_read, cache_write_5m, cache_write_1h, long_context_input, output, reasoning } }, 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