RankedLM MCP Server

An auditable MCP gateway exposing 4 tools to agents — with JWT authentication, immutable PostgreSQL audit logs, and a FastAPI auth layer. Runs in Docker. One command to start.

---

Quick Start

# 1. Clone and enter the project
cd rankedlm

# 2. Copy env file
cp .env.example .env

# 3. Start the full stack
docker-compose up --build

# 4. Run the demo agent (in a second terminal)
python agent_demo/demo_agent.py

The demo agent uses the pre-seeded test key: rankedlm-test-key-001

---

Testing

A manual test file is included at agent_demo/test_manual.py. It tests all 4 tools, JWT auth, and middleware in sequence.

Run it: python3 agent_demo/test_manual.py

To test failure cases, open the file and change the values marked with # <-- CHANGE THIS comments.

---

Endpoints

Layer	Method	Path	Purpose	Auth
FastAPI	POST	/auth/token	API key → JWT exchange	API key
FastAPI	GET	/health	Health check	None
FastMCP	POST	/mcp	All 4 MCP tools (JSON-RPC)	JWT

---

The 4 Tools

validate_permissions

Checks whether the calling agent's JWT scope satisfies a required permission level before tool execution. Read-only — no DB write. Returns allowed, reason, the agent's current scope_level, and a checked_at timestamp.

log_tool_call

Writes an immutable audit entry to audit_logs. The scope_used field is derived from the validated JWT on the server — the agent cannot supply or forge it. Returns a log_id, timestamp, and immutable: true.

request_tool_access

Submits an elevation request for a restricted tool. Creates a record in access_requests with status pending. Approval is handled via direct DB update or an admin endpoint. Every escalation is a traceable record — there are no silent grants.

audit_access_history

Paginated query over audit_logs with optional filters: user_id, tool_name, from_date, to_date, limit. Returns logs, total_count, and has_more.

---

Authentication Flow

Agent
  → POST /auth/token  { "api_key": "..." }
  ← { "access_token": "<JWT>", "expires_in": 3600 }

Agent
  → POST /mcp  Authorization: Bearer <JWT>
  ← tool result

JWT payload:

{
  "user_id": "agent_001",
  "scopes": ["read", "write"],
  "rate_limit_rpm": 100,
  "exp": 1234567890,
  "iat": 1234567800,
  "jti": "uuid"
}

---

Scope Tiers

Scope	Permitted Tools
read	validate_permissions, audit_access_history
write	All read tools + log_tool_call, request_tool_access
admin	Reserved — v2

---

How I Designed for Auditability

Every claim below is backed by a specific architectural decision in the codebase — not documentation added after the fact.

1. Inputs are never stored raw log_tool_call accepts input_hash (SHA-256), not raw input. The agent hashes before calling. The database never sees plaintext tool arguments. Sensitive data cannot leak through the audit trail.

2. Audit logs are structurally immutable The audit_logs table has no updated_at column and no UPDATE path anywhere in the codebase. Immutability is enforced by schema omission, not by application-layer policy that could be bypassed.

3. Every call carries its own permission proof scope_used in audit_logs is always derived from the validated JWT by the server — app/mcp/server.py:log_tool_call. The agent cannot supply or manipulate this field. Every audit row is self-evidencing.

4. Escalation is always a traceable record request_tool_access creates a row in access_requests before any grant is possible. There is no code path that elevates a scope silently. Approvals happen via DB update or admin endpoint — both leave a resolved_by and resolved_at trail.

5. Revocation was planned for, not bolted on jti (JWT ID) is included in every token payload. A revoked_tokens table is not implemented in v1 — JWTs expire naturally via exp. The jti field exists so revocation can be added in v2 without changing the token structure.

6. Key security is applied consistently API keys are stored as SHA-256 hashes (key_hash in api_keys). Raw keys are never written to the database. The same hashing principle applies to input_hash in audit_logs. One security model, applied system-wide.

7. Abuse prevention is in the data model rate_limit_rpm lives as a column on api_keys — not hardcoded in middleware. Each key carries its own limit. Changing a key's rate limit requires a DB update, which is itself auditable. The limit is embedded in the JWT so enforcement requires no per-request DB lookup.

8. The audit trail is independently verifiable docker-compose up starts the full stack in under 60 seconds. Any engineer can spin up the environment, run the demo agent, and query audit_logs directly in Postgres — no proprietary tooling, no access request needed. Auditability that requires special access is not real auditability.

---

Claude Desktop Config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "rankedlm": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-here>"
      }
    }
  }
}

Get a JWT first:

curl -X POST http://localhost:8000/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "rankedlm-test-key-001"}'

---

Project Structure

rankedlm/
├── docker-compose.yml
├── Dockerfile
├── init.sql                  ← schema + seed key
├── pyproject.toml
├── .env.example
├── app/
│   ├── main.py               ← FastAPI app, mounts FastMCP at /mcp
│   ├── auth/
│   │   ├── api_key_handler.py
│   │   └── jwt_handler.py
│   ├── db/
│   │   ├── connection.py
│   │   └── queries.py
│   ├── middleware/
│   │   ├── jwt_middleware.py
│   │   └── rate_limiter.py
│   ├── models/
│   │   └── schemas.py
│   ├── routes/
│   │   ├── auth.py
│   │   └── health.py
│   └── mcp/
│       └── server.py         ← 4 MCP tools
└── agent_demo/
    └── demo_agent.py