MCP & OAuth Architecture

Backend architecture reference for the MCP server and OAuth connector subsystems, covering the data model, control flow, validation, and extensibility.

---

Overview

This document targets backend engineers who are extending or operating the MCP server and OAuth connector subsystems. It summarizes the data model, control flow, and key modules involved in provisioning external integrations.

Component Map

Data Model Relationships

• OauthProvider exposes one or more OauthService entries.
• OauthService grants ConnectedService records (per user, per platform).
• MCPServer is registered on a Platform and has one or more MCPServerConnection entries.
• MCPServerConnection optionally uses a ConnectedService (for OAuth-backed auth) and can be scoped to a Mentor.
• ConnectedService has a unique constraint on (user, provider, platform, service) to enforce one connection per surface.

Connection scope rules

• scope="platform" -- platform is auto-filled from the server's platform (unless featured).
• scope="user" -- Requires user or connected_service.
• scope="mentor" -- Requires a mentor; optionally reuses platform-level credentials when no mentor-specific ones exist.
• auth_type="oauth2" -- Always requires connected_service.

OAuth Flow Internals

Discovery

OAuthServiceListAPIView surfaces enabled services. OAuthServiceScopeListAPIView narrows down to a specific service scope.

Start

The start view resolves scopes, builds the provider adapter, and stores a UUID-based hash in the cache to guard the callback. Cache entries expire after one hour to limit replay windows.

Callback

The callback view verifies state, exchanges the code for a token, normalizes the scope/service identifier, and syncs metadata. Tokens are stored raw (access_token, refresh_token, token_type) and lowercased for schema consistency.

Refresh

Downstream modules call the refresh function which uses the provider adapter to refresh tokens and re-sync metadata.

Error handling is intentionally strict: multiple services per connection raise ValueError early; missing tenant credentials return 404/400 responses.

MCP Server Runtime Resolution

LangChain Tool -> MCPServer.resolve_connection(platform, user, mentor)
                   |
                   |- User-scoped connection exists?
                   |    YES -> Load connection -> Optional ConnectedService (if oauth2)
                   |
                   |- Mentor-scoped connection exists?
                   |    YES -> Use mentor credentials
                   |
                   |- Platform-scoped connection exists?
                   |    YES -> Use stored platform credentials
                   |
                   |- Server is featured?
                   |    YES -> Use global connection
                   |    NO  -> Fail with 401 / no connection
                   |
                   -> render_headers(access_token?)
                      If oauth2: ensure fresh access token (refresh if needed)
                      Return: authorization headers

Async code paths use aresolve_connection() with .afirst() queries to avoid blocking the event loop. Headers are merged with extra_headers, and explicit credentials override anything pre-existing.

Validation and Security

Credential sourcing

get_cred("auth_{provider}", tenant) is the single source of truth for client IDs and secrets. Tenant-specific overrides live alongside global (tenant="main") credentials. The serializer guard ensures the admin has installed the necessary client credentials before connections are created.

State integrity

Cache entries expire after one hour. The callback splits state into (org, provider, service, user_id, hash) and verifies the cached value before exchanging the token.

Access control

• OAuth endpoints restrict methods (GET, DELETE) to read-only client operations, leaving creation solely to the managed OAuth flow.
• MCP endpoints require tenant admin privileges for all create/update/delete operations.

Extensibility

Adding a new OAuth provider/service

1. Seed OauthProvider and OauthService records via the management command.
2. Provision client credentials (auth_{provider}) in the credential store.
3. Update the front-end to surface the new service (the API is discovery-driven, so minimal UI changes are needed).

Extending MCP authentication types

1. Add a new enum member to MCPServer.AuthType.
2. Extend connection validation to handle the new type.
3. Update render_headers() to format the outbound headers.
4. Update front-end forms and documentation.

Supporting multi-tenant shared servers

Mark the server is_featured=true. Platform admins in other tenants can then create their own connections, while the original tenant retains control of the server metadata.