System ArchitectureRFC 9728 / RFC 8414

Protocol & Server Architecture

An in-depth look at how Krafto separates Authorization from Resource Serving, enforces OAuth 2.1 standards, uses Streamable HTTP transports, and eliminates shared secrets.

Architecture Overview

Authorization Server (apps/api)

Implemented in ASP.NET Core Modular Monolith (.NET 9). Handles user identity, database persistence (PostgreSQL), dynamic client registration, PKCE authorization code exchanges, and serves RFC 8414 metadata at /.well-known/oauth-authorization-server.

Protected Resource Server (apps/mcp)

Standalone Node.js / TypeScript microservice executing the Model Context Protocol SDK over Streamable HTTP (POST /mcp). Talks to apps/api strictly over authenticated HTTP — zero direct database connections.

RFC 9728 Protected Resource Metadata

At startup, the MCP service dynamically fetches the API's live OAuth metadata from /.well-known/oauth-authorization-server and republishes its own protected-resource metadata at /.well-known/oauth-protected-resource/mcp. This guarantees that client scopes, issuers, and endpoints never drift out of sync.

{
  "resource": "https://api.trykrafto.xyz/mcp",
  "authorization_servers": [
    "https://api.trykrafto.xyz"
  ],
  "scopes_supported": [
    "catalog:read",
    "library:read",
    "library:claim",
    "library:download",
    "account:read",
    "wallet:spend",
    "wishlist:manage",
    "reviews:write",
    "bundles:manage"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_documentation": "https://www.trykrafto.xyz/docs"
}

Zero-Trust Token Verification

Rather than distributing the API's JWT signing keys to the MCP server process (which would create duplicate secret surfaces), KraftoTokenVerifier validates tokens in real-time by querying GET /api/v1/auth/userinfo on every MCP session.

Instant Suspension: Revoking a user in Admin immediately blocks tool calls mid-session.

Dynamic Tier Upgrades: Changing from Free to Pro immediately expands tool quotas.

Fire-and-Forget Tool Telemetry

Every tool invocation is wrapped by an instrumentation layer that logs latency, success status, and caller identity to POST /api/v1/mcp/usage/log asynchronously. Telemetry operations are fire-and-forget and cannot delay or fail tool responses.

Quickstarts

Auth & Scopes