Skip to main content

Guidelines

This is a collection of guidelines that we follow to build our projects. It's a living document, so please feel free to contribute to it.

Scopes​

📄️MCP Server with OAuth

This guideline shows how to build a Model Context Protocol (MCP) server that authenticates MCP clients (Claude, Cursor, VS Code) with OAuth 2.1, using only ttoss packages. No external auth framework is required: @ttoss/http-server provides the Koa runtime, @ttoss/http-server-mcp provides both halves of MCP authorization, and @ttoss/auth-core provides the token primitives. Your app keeps its own user model, signing keys, and login UI — ttoss owns only the protocol mechanics.

📄️OAuth Authorization Server — Issuing Tokens for Your Own App

This guideline covers an app acting as an OAuth 2.1 authorization server: it lets clients register, runs the login/consent flow against your existing user model, and issues access and refresh tokens. The spec mechanics (RFC 8414, 7591, 7636, 6749, 9728) live in a runner-agnostic engine — createOAuthHandlers in @ttoss/auth-core — that operates on plain request/response objects, so any runtime can host it. @ttoss/http-server-auth ships the Koa adapter, oauthServer(); an AWS Lambda or GraphQL runner would adapt the same engine. Your app keeps its user model, signing keys, and login UI behind hooks.

📄️OAuth Client — Connecting to Third-Party Providers

This guideline covers an app acting as an OAuth client: it sends a user to a third-party provider (TikTok, Instagram, YouTube, Google, …), receives an access token on their behalf, stores it, and uses it later — including from background jobs where no user is present. It is the inverse of MCP Server with OAuth, where your app is the authorization/resource server that MCP clients authenticate against. Here a remote provider owns the tokens and your app is the one logging in.