# LLMRing Server - LLM Documentation

URL: https://llmring.ai/docs/server/
This is the LLM-readable version of the LLMRing Server page.

---

## LLMRing Server

**GitHub**: [https://github.com/juanre/llmring-server](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

```bash
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

```bash
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"
  }
}```

```bash
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, 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:

```python
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