@routecraft/ai 0.4.0 → 0.5.0-canary.2

package/dist/index.d.cts

@@ -495,17 +495,61 @@ interface AuthPrincipal {
     claims?: Record<string, unknown>;
 }
 /**
- * Authentication options for the MCP HTTP server.
- * Only applies when `transport` is `"http"`. Ignored for stdio.
+ * Token info returned by the OAuth `verifyAccessToken` callback.
+ * Mirrors the MCP SDK's `AuthInfo` with only the fields routecraft needs.
  *
- * The validator receives the raw bearer token from the `Authorization` header
- * on every request and must return an {@link AuthPrincipal} on success or
- * `null` / `false` to reject with 401. Use the built-in `jwt()` helper for
- * HMAC-signed JWTs or supply a custom function for other schemes.
+ * @experimental
+ */
+interface OAuthTokenInfo {
+    /** The raw access token string. */
+    token: string;
+    /** OAuth client ID that obtained this token. */
+    clientId: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Expiry as Unix epoch seconds. */
+    expiresAt?: number;
+}
+/**
+ * OAuth client info returned by the `getClient` callback.
+ * Mirrors the MCP SDK's `OAuthClientInformationFull` with only the fields routecraft needs.
+ *
+ * Field names use snake_case to match the OAuth 2.0 Dynamic Client Registration
+ * specification (RFC 7591) and the MCP SDK's `OAuthClientInformationFull`.
+ *
+ * @experimental
+ */
+interface OAuthClientInfo {
+    /** The client identifier. */
+    client_id: string;
+    /** Allowed redirect URIs for authorization code flow. */
+    redirect_uris: string[];
+    /** Human-readable client name. */
+    client_name?: string;
+    /** Client secret (for confidential clients). */
+    client_secret?: string;
+}
+/**
+ * Endpoint URLs for the upstream OAuth provider (used by the proxy).
+ *
+ * @experimental
+ */
+interface OAuthProxyEndpoints {
+    /** Authorization endpoint URL. */
+    authorizationUrl: string;
+    /** Token endpoint URL. */
+    tokenUrl: string;
+    /** Token revocation endpoint URL. */
+    revocationUrl?: string;
+    /** Dynamic client registration endpoint URL. */
+    registrationUrl?: string;
+}
+/**
+ * Validator-based auth: bearer token checked on every request.
+ * Used with `jwt()` helper or custom validator functions.
  *
  * @example
  * ```ts
- * // Built-in JWT helper (HMAC / HS256)
  * import { jwt } from "@routecraft/ai";
  * auth: jwt({ secret: process.env.JWT_SECRET! })
  *
@@ -521,7 +565,7 @@ interface AuthPrincipal {
  *
  * @experimental
  */
-interface McpHttpAuthOptions {
+interface McpValidatorAuthOptions {
     /**
      * Validator function called with the raw bearer token on every request.
      *
@@ -533,6 +577,70 @@ interface McpHttpAuthOptions {
      */
     validator: McpAuthValidator;
 }
+/**
+ * OAuth provider auth: full OAuth 2.1 server flow with proxy to upstream IdP.
+ * Mounts discovery, authorization, token, and revocation endpoints alongside `/mcp`.
+ * Uses the MCP SDK's `ProxyOAuthServerProvider` and `mcpAuthRouter` internally.
+ *
+ * @example
+ * ```ts
+ * import { oauth } from "@routecraft/ai";
+ * auth: oauth({
+ *   issuerUrl: "https://mcp.example.com",
+ *   endpoints: {
+ *     authorizationUrl: "https://idp.example.com/authorize",
+ *     tokenUrl: "https://idp.example.com/token",
+ *   },
+ *   verifyAccessToken: async (token) => ({
+ *     token, clientId: "my-client", scopes: ["read"],
+ *   }),
+ *   getClient: async (clientId) => ({
+ *     client_id: clientId, redirect_uris: ["http://localhost:3000/callback"],
+ *   }),
+ * })
+ * ```
+ *
+ * @experimental
+ */
+interface McpOAuthAuthOptions {
+    /** Discriminant for the union. Always `"oauth"`. */
+    provider: "oauth";
+    /** Issuer URL for OAuth metadata discovery. Must be HTTPS in production. */
+    issuerUrl: string | URL;
+    /** Base URL for OAuth endpoints (defaults to issuerUrl). */
+    baseUrl?: string | URL;
+    /** Upstream OAuth provider endpoints to proxy. */
+    endpoints: OAuthProxyEndpoints;
+    /**
+     * Verify an access token and return token info.
+     * Called on every authenticated request to `/mcp`.
+     */
+    verifyAccessToken: (token: string) => Promise<OAuthTokenInfo>;
+    /**
+     * Look up a registered OAuth client by ID.
+     * Return `undefined` to reject the client.
+     */
+    getClient: (clientId: string) => Promise<OAuthClientInfo | undefined>;
+    /** OAuth scopes the server advertises as supported. */
+    scopesSupported?: string[];
+    /** Scopes required on every request to `/mcp`. */
+    requiredScopes?: string[];
+    /** URL to service documentation (included in OAuth metadata). */
+    serviceDocumentationUrl?: string | URL;
+    /** Human-readable resource name (included in OAuth metadata). */
+    resourceName?: string;
+}
+/**
+ * Authentication options for the MCP HTTP server.
+ * Only applies when `transport` is `"http"`. Ignored for stdio.
+ *
+ * Two strategies are supported:
+ * - `Validator`: simple bearer token check via `jwt()` or custom function.
+ * - `OAuth`: full OAuth 2.1 server flow via `oauth()`, proxying to an upstream IdP.
+ *
+ * @experimental
+ */
+type McpHttpAuthOptions = McpValidatorAuthOptions | McpOAuthAuthOptions;
 /**
  * A function that validates a bearer token and resolves the authenticated principal.
  * Called on every incoming HTTP request.
@@ -883,6 +991,77 @@ type JwtAuthOptions = JwtHmacOptions | JwtRsaOptions;
  */
 declare function jwt(options: JwtAuthOptions): McpHttpAuthOptions;
 
+/**
+ * Options for the `oauth()` factory.
+ *
+ * @experimental
+ */
+interface OAuthFactoryOptions {
+    /** Issuer URL for OAuth metadata discovery. Must be HTTPS in production. */
+    issuerUrl: string | URL;
+    /** Base URL for OAuth endpoints (defaults to issuerUrl). */
+    baseUrl?: string | URL;
+    /** Upstream OAuth provider endpoints to proxy. */
+    endpoints: OAuthProxyEndpoints;
+    /**
+     * Verify an access token and return token info.
+     * Called on every authenticated request to `/mcp`.
+     */
+    verifyAccessToken: (token: string) => Promise<OAuthTokenInfo>;
+    /**
+     * Look up a registered OAuth client by ID.
+     * Return `undefined` to reject the client.
+     */
+    getClient: (clientId: string) => Promise<OAuthClientInfo | undefined>;
+    /** OAuth scopes the server advertises as supported. */
+    scopesSupported?: string[];
+    /** Scopes required on every request to `/mcp`. */
+    requiredScopes?: string[];
+    /** URL to service documentation (included in OAuth metadata). */
+    serviceDocumentationUrl?: string | URL;
+    /** Human-readable resource name (included in OAuth metadata). */
+    resourceName?: string;
+}
+/**
+ * Built-in OAuth authentication helper for MCP HTTP servers.
+ * Configures a full OAuth 2.1 server flow that proxies to an upstream identity
+ * provider using the MCP SDK's `ProxyOAuthServerProvider` and `mcpAuthRouter`.
+ *
+ * Returns an {@link McpHttpAuthOptions} that can be passed directly to
+ * `mcpPlugin({ auth: oauth({ ... }) })`.
+ *
+ * The server will mount OAuth endpoints (`/.well-known/oauth-authorization-server`,
+ * `/authorize`, `/token`, `/revoke`) alongside the `/mcp` transport endpoint.
+ *
+ * @example
+ * ```ts
+ * import { mcpPlugin, oauth } from "@routecraft/ai";
+ *
+ * mcpPlugin({
+ *   transport: "http",
+ *   auth: oauth({
+ *     issuerUrl: "https://mcp.example.com",
+ *     endpoints: {
+ *       authorizationUrl: "https://idp.example.com/authorize",
+ *       tokenUrl: "https://idp.example.com/token",
+ *     },
+ *     verifyAccessToken: async (token) => ({
+ *       token,
+ *       clientId: "my-client",
+ *       scopes: ["read"],
+ *     }),
+ *     getClient: async (clientId) => ({
+ *       client_id: clientId,
+ *       redirect_uris: ["http://localhost:3000/callback"],
+ *     }),
+ *   }),
+ * });
+ * ```
+ *
+ * @experimental
+ */
+declare function oauth(options: OAuthFactoryOptions): McpOAuthAuthOptions;
+
 /**
  * MCP plugin: one plugin per adapter. Starts the MCP server during plugin apply (before routes start) so startup failures fail context build. Exposes mcp() routes to external MCP clients.
  * Optional clients: register named remote MCP servers so routes can use .to(mcp("name:tool")) without passing url.
@@ -908,7 +1087,10 @@ declare class McpServer {
     private options;
     private server;
     private transport;
-    /** Node HTTP server when transport is http; used to listen on port and close on stop. */
+    /**
+     * Node HTTP server when transport is http; used to listen on port and close on stop.
+     * When OAuth is enabled this holds the Express app's underlying server.
+     */
     private httpServer;
     /** Active HTTP sessions keyed by session ID (each session has its own server+transport pair). */
     private httpSessions;
@@ -925,18 +1107,56 @@ declare class McpServer {
     private startStdio;
     /**
      * Start HTTP transport (streamable-http).
-     * Creates a Node HTTP server that manages per-session MCP server+transport pairs.
-     * Each client session (identified by the `mcp-session-id` header) gets its own
-     * Server and StreamableHTTPServerTransport so that reconnecting clients can
-     * establish fresh sessions without restarting the process.
+     * Dispatches to the OAuth or raw-HTTP path depending on the auth config.
      */
     private startHttp;
+    /**
+     * Import the MCP SDK Server constructor and StreamableHTTPServerTransport.
+     * Shared by both HTTP startup paths.
+     */
+    private importSdkHttp;
+    /**
+     * Creates a new MCP Server + Transport pair for a single HTTP session.
+     * Called on every initialization request (no session ID header).
+     */
+    private createSession;
+    /**
+     * Route an MCP request through session management with principal context.
+     * Shared by both HTTP startup paths.
+     */
+    private handleMcpRequest;
+    /**
+     * Start HTTP transport with validator-based auth (existing behavior).
+     * Uses raw Node.js `http.createServer`.
+     */
+    private startHttpWithValidator;
+    /**
+     * Start HTTP transport with OAuth provider auth.
+     * Uses Express to mount `mcpAuthRouter` (OAuth endpoints) alongside `/mcp`.
+     * Express is available as a transitive dependency of `@modelcontextprotocol/sdk`.
+     *
+     * Note: if the server runs behind a reverse proxy, `req.ip` and `req.protocol`
+     * may be incorrect. Users should set `trust proxy` on the Express app via a
+     * future configuration option or by using a custom HTTP server.
+     */
+    private startHttpWithOAuth;
+    /**
+     * Bind the HTTP server to the configured port and host.
+     * Used by the validator path.
+     */
+    private listenHttp;
+    /**
+     * Convert the MCP SDK's AuthInfo (set by requireBearerAuth) to an AuthPrincipal
+     * for routecraft's exchange headers.
+     */
+    private authInfoToPrincipal;
     /**
      * When transport is http, returns the bound port (useful when port 0 was used). Otherwise undefined.
      */
     getHttpPort(): number | undefined;
     /**
      * Validate the Authorization header using the configured validator.
+     * Only used on the validator auth path (not OAuth -- that uses Express middleware).
      * Returns the authenticated principal on success, or `null` to reject with 401.
      */
     private validateAuth;
@@ -1155,4 +1375,4 @@ declare function embeddingPlugin(options?: EmbeddingPluginOptions): CraftPlugin;
  */
 declare function disposeEmbeddingPipelineCache(): Promise<void>;
 
-export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, type AuthPrincipal, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type JwtAuthOptions, type JwtHmacOptions, type JwtRsaOptions, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpAuthValidator, type McpClientAuthOptions, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpClientTokenProvider, McpHeadersKeys, type McpHttpAuthOptions, type McpMessage, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, jwt, llm, llmPlugin, mcp, mcpPlugin, validateLlmPluginOptions, validateWithSchema };
+export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, type AuthPrincipal, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type JwtAuthOptions, type JwtHmacOptions, type JwtRsaOptions, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpAuthValidator, type McpClientAuthOptions, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpClientTokenProvider, McpHeadersKeys, type McpHttpAuthOptions, type McpMessage, type McpOAuthAuthOptions, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type McpValidatorAuthOptions, type OAuthClientInfo, type OAuthFactoryOptions, type OAuthProxyEndpoints, type OAuthTokenInfo, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, jwt, llm, llmPlugin, mcp, mcpPlugin, oauth, validateLlmPluginOptions, validateWithSchema };

package/dist/index.d.ts

@@ -495,17 +495,61 @@ interface AuthPrincipal {
     claims?: Record<string, unknown>;
 }
 /**
- * Authentication options for the MCP HTTP server.
- * Only applies when `transport` is `"http"`. Ignored for stdio.
+ * Token info returned by the OAuth `verifyAccessToken` callback.
+ * Mirrors the MCP SDK's `AuthInfo` with only the fields routecraft needs.
  *
- * The validator receives the raw bearer token from the `Authorization` header
- * on every request and must return an {@link AuthPrincipal} on success or
- * `null` / `false` to reject with 401. Use the built-in `jwt()` helper for
- * HMAC-signed JWTs or supply a custom function for other schemes.
+ * @experimental
+ */
+interface OAuthTokenInfo {
+    /** The raw access token string. */
+    token: string;
+    /** OAuth client ID that obtained this token. */
+    clientId: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Expiry as Unix epoch seconds. */
+    expiresAt?: number;
+}
+/**
+ * OAuth client info returned by the `getClient` callback.
+ * Mirrors the MCP SDK's `OAuthClientInformationFull` with only the fields routecraft needs.
+ *
+ * Field names use snake_case to match the OAuth 2.0 Dynamic Client Registration
+ * specification (RFC 7591) and the MCP SDK's `OAuthClientInformationFull`.
+ *
+ * @experimental
+ */
+interface OAuthClientInfo {
+    /** The client identifier. */
+    client_id: string;
+    /** Allowed redirect URIs for authorization code flow. */
+    redirect_uris: string[];
+    /** Human-readable client name. */
+    client_name?: string;
+    /** Client secret (for confidential clients). */
+    client_secret?: string;
+}
+/**
+ * Endpoint URLs for the upstream OAuth provider (used by the proxy).
+ *
+ * @experimental
+ */
+interface OAuthProxyEndpoints {
+    /** Authorization endpoint URL. */
+    authorizationUrl: string;
+    /** Token endpoint URL. */
+    tokenUrl: string;
+    /** Token revocation endpoint URL. */
+    revocationUrl?: string;
+    /** Dynamic client registration endpoint URL. */
+    registrationUrl?: string;
+}
+/**
+ * Validator-based auth: bearer token checked on every request.
+ * Used with `jwt()` helper or custom validator functions.
  *
  * @example
  * ```ts
- * // Built-in JWT helper (HMAC / HS256)
  * import { jwt } from "@routecraft/ai";
  * auth: jwt({ secret: process.env.JWT_SECRET! })
  *
@@ -521,7 +565,7 @@ interface AuthPrincipal {
  *
  * @experimental
  */
-interface McpHttpAuthOptions {
+interface McpValidatorAuthOptions {
     /**
      * Validator function called with the raw bearer token on every request.
      *
@@ -533,6 +577,70 @@ interface McpHttpAuthOptions {
      */
     validator: McpAuthValidator;
 }
+/**
+ * OAuth provider auth: full OAuth 2.1 server flow with proxy to upstream IdP.
+ * Mounts discovery, authorization, token, and revocation endpoints alongside `/mcp`.
+ * Uses the MCP SDK's `ProxyOAuthServerProvider` and `mcpAuthRouter` internally.
+ *
+ * @example
+ * ```ts
+ * import { oauth } from "@routecraft/ai";
+ * auth: oauth({
+ *   issuerUrl: "https://mcp.example.com",
+ *   endpoints: {
+ *     authorizationUrl: "https://idp.example.com/authorize",
+ *     tokenUrl: "https://idp.example.com/token",
+ *   },
+ *   verifyAccessToken: async (token) => ({
+ *     token, clientId: "my-client", scopes: ["read"],
+ *   }),
+ *   getClient: async (clientId) => ({
+ *     client_id: clientId, redirect_uris: ["http://localhost:3000/callback"],
+ *   }),
+ * })
+ * ```
+ *
+ * @experimental
+ */
+interface McpOAuthAuthOptions {
+    /** Discriminant for the union. Always `"oauth"`. */
+    provider: "oauth";
+    /** Issuer URL for OAuth metadata discovery. Must be HTTPS in production. */
+    issuerUrl: string | URL;
+    /** Base URL for OAuth endpoints (defaults to issuerUrl). */
+    baseUrl?: string | URL;
+    /** Upstream OAuth provider endpoints to proxy. */
+    endpoints: OAuthProxyEndpoints;
+    /**
+     * Verify an access token and return token info.
+     * Called on every authenticated request to `/mcp`.
+     */
+    verifyAccessToken: (token: string) => Promise<OAuthTokenInfo>;
+    /**
+     * Look up a registered OAuth client by ID.
+     * Return `undefined` to reject the client.
+     */
+    getClient: (clientId: string) => Promise<OAuthClientInfo | undefined>;
+    /** OAuth scopes the server advertises as supported. */
+    scopesSupported?: string[];
+    /** Scopes required on every request to `/mcp`. */
+    requiredScopes?: string[];
+    /** URL to service documentation (included in OAuth metadata). */
+    serviceDocumentationUrl?: string | URL;
+    /** Human-readable resource name (included in OAuth metadata). */
+    resourceName?: string;
+}
+/**
+ * Authentication options for the MCP HTTP server.
+ * Only applies when `transport` is `"http"`. Ignored for stdio.
+ *
+ * Two strategies are supported:
+ * - `Validator`: simple bearer token check via `jwt()` or custom function.
+ * - `OAuth`: full OAuth 2.1 server flow via `oauth()`, proxying to an upstream IdP.
+ *
+ * @experimental
+ */
+type McpHttpAuthOptions = McpValidatorAuthOptions | McpOAuthAuthOptions;
 /**
  * A function that validates a bearer token and resolves the authenticated principal.
  * Called on every incoming HTTP request.
@@ -883,6 +991,77 @@ type JwtAuthOptions = JwtHmacOptions | JwtRsaOptions;
  */
 declare function jwt(options: JwtAuthOptions): McpHttpAuthOptions;
 
+/**
+ * Options for the `oauth()` factory.
+ *
+ * @experimental
+ */
+interface OAuthFactoryOptions {
+    /** Issuer URL for OAuth metadata discovery. Must be HTTPS in production. */
+    issuerUrl: string | URL;
+    /** Base URL for OAuth endpoints (defaults to issuerUrl). */
+    baseUrl?: string | URL;
+    /** Upstream OAuth provider endpoints to proxy. */
+    endpoints: OAuthProxyEndpoints;
+    /**
+     * Verify an access token and return token info.
+     * Called on every authenticated request to `/mcp`.
+     */
+    verifyAccessToken: (token: string) => Promise<OAuthTokenInfo>;
+    /**
+     * Look up a registered OAuth client by ID.
+     * Return `undefined` to reject the client.
+     */
+    getClient: (clientId: string) => Promise<OAuthClientInfo | undefined>;
+    /** OAuth scopes the server advertises as supported. */
+    scopesSupported?: string[];
+    /** Scopes required on every request to `/mcp`. */
+    requiredScopes?: string[];
+    /** URL to service documentation (included in OAuth metadata). */
+    serviceDocumentationUrl?: string | URL;
+    /** Human-readable resource name (included in OAuth metadata). */
+    resourceName?: string;
+}
+/**
+ * Built-in OAuth authentication helper for MCP HTTP servers.
+ * Configures a full OAuth 2.1 server flow that proxies to an upstream identity
+ * provider using the MCP SDK's `ProxyOAuthServerProvider` and `mcpAuthRouter`.
+ *
+ * Returns an {@link McpHttpAuthOptions} that can be passed directly to
+ * `mcpPlugin({ auth: oauth({ ... }) })`.
+ *
+ * The server will mount OAuth endpoints (`/.well-known/oauth-authorization-server`,
+ * `/authorize`, `/token`, `/revoke`) alongside the `/mcp` transport endpoint.
+ *
+ * @example
+ * ```ts
+ * import { mcpPlugin, oauth } from "@routecraft/ai";
+ *
+ * mcpPlugin({
+ *   transport: "http",
+ *   auth: oauth({
+ *     issuerUrl: "https://mcp.example.com",
+ *     endpoints: {
+ *       authorizationUrl: "https://idp.example.com/authorize",
+ *       tokenUrl: "https://idp.example.com/token",
+ *     },
+ *     verifyAccessToken: async (token) => ({
+ *       token,
+ *       clientId: "my-client",
+ *       scopes: ["read"],
+ *     }),
+ *     getClient: async (clientId) => ({
+ *       client_id: clientId,
+ *       redirect_uris: ["http://localhost:3000/callback"],
+ *     }),
+ *   }),
+ * });
+ * ```
+ *
+ * @experimental
+ */
+declare function oauth(options: OAuthFactoryOptions): McpOAuthAuthOptions;
+
 /**
  * MCP plugin: one plugin per adapter. Starts the MCP server during plugin apply (before routes start) so startup failures fail context build. Exposes mcp() routes to external MCP clients.
  * Optional clients: register named remote MCP servers so routes can use .to(mcp("name:tool")) without passing url.
@@ -908,7 +1087,10 @@ declare class McpServer {
     private options;
     private server;
     private transport;
-    /** Node HTTP server when transport is http; used to listen on port and close on stop. */
+    /**
+     * Node HTTP server when transport is http; used to listen on port and close on stop.
+     * When OAuth is enabled this holds the Express app's underlying server.
+     */
     private httpServer;
     /** Active HTTP sessions keyed by session ID (each session has its own server+transport pair). */
     private httpSessions;
@@ -925,18 +1107,56 @@ declare class McpServer {
     private startStdio;
     /**
      * Start HTTP transport (streamable-http).
-     * Creates a Node HTTP server that manages per-session MCP server+transport pairs.
-     * Each client session (identified by the `mcp-session-id` header) gets its own
-     * Server and StreamableHTTPServerTransport so that reconnecting clients can
-     * establish fresh sessions without restarting the process.
+     * Dispatches to the OAuth or raw-HTTP path depending on the auth config.
      */
     private startHttp;
+    /**
+     * Import the MCP SDK Server constructor and StreamableHTTPServerTransport.
+     * Shared by both HTTP startup paths.
+     */
+    private importSdkHttp;
+    /**
+     * Creates a new MCP Server + Transport pair for a single HTTP session.
+     * Called on every initialization request (no session ID header).
+     */
+    private createSession;
+    /**
+     * Route an MCP request through session management with principal context.
+     * Shared by both HTTP startup paths.
+     */
+    private handleMcpRequest;
+    /**
+     * Start HTTP transport with validator-based auth (existing behavior).
+     * Uses raw Node.js `http.createServer`.
+     */
+    private startHttpWithValidator;
+    /**
+     * Start HTTP transport with OAuth provider auth.
+     * Uses Express to mount `mcpAuthRouter` (OAuth endpoints) alongside `/mcp`.
+     * Express is available as a transitive dependency of `@modelcontextprotocol/sdk`.
+     *
+     * Note: if the server runs behind a reverse proxy, `req.ip` and `req.protocol`
+     * may be incorrect. Users should set `trust proxy` on the Express app via a
+     * future configuration option or by using a custom HTTP server.
+     */
+    private startHttpWithOAuth;
+    /**
+     * Bind the HTTP server to the configured port and host.
+     * Used by the validator path.
+     */
+    private listenHttp;
+    /**
+     * Convert the MCP SDK's AuthInfo (set by requireBearerAuth) to an AuthPrincipal
+     * for routecraft's exchange headers.
+     */
+    private authInfoToPrincipal;
     /**
      * When transport is http, returns the bound port (useful when port 0 was used). Otherwise undefined.
      */
     getHttpPort(): number | undefined;
     /**
      * Validate the Authorization header using the configured validator.
+     * Only used on the validator auth path (not OAuth -- that uses Express middleware).
      * Returns the authenticated principal on success, or `null` to reject with 401.
      */
     private validateAuth;
@@ -1155,4 +1375,4 @@ declare function embeddingPlugin(options?: EmbeddingPluginOptions): CraftPlugin;
  */
 declare function disposeEmbeddingPipelineCache(): Promise<void>;
 
-export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, type AuthPrincipal, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type JwtAuthOptions, type JwtHmacOptions, type JwtRsaOptions, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpAuthValidator, type McpClientAuthOptions, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpClientTokenProvider, McpHeadersKeys, type McpHttpAuthOptions, type McpMessage, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, jwt, llm, llmPlugin, mcp, mcpPlugin, validateLlmPluginOptions, validateWithSchema };
+export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, type AuthPrincipal, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type JwtAuthOptions, type JwtHmacOptions, type JwtRsaOptions, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpAuthValidator, type McpClientAuthOptions, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpClientTokenProvider, McpHeadersKeys, type McpHttpAuthOptions, type McpMessage, type McpOAuthAuthOptions, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type McpValidatorAuthOptions, type OAuthClientInfo, type OAuthFactoryOptions, type OAuthProxyEndpoints, type OAuthTokenInfo, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, jwt, llm, llmPlugin, mcp, mcpPlugin, oauth, validateLlmPluginOptions, validateWithSchema };