Feature: OAuth authentication + Streamable HTTP (#13)

* rename

* rename

* rename

* rename

* fix: examples

* examples

* examples

oauth

oauth

* ignore

* references

* reference

* fix: stdio

* fix: streamable http

* fix: oauth

* fix: oauth

* rm: anaconda oauth example

Author: echarles

.gitignore

@@ -14,6 +14,8 @@
 *.pyc
 **/__pycache__
 
+**/config.json
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -369,15 +369,15 @@ See the [Git-File Example README](examples/git-file/README.md) for complete docu
 
 Production-ready example with GitHub OAuth2 authentication.
 
-**Location:** [`examples/mcp-auth/`](examples/mcp-auth/)
+**Location:** [`references/oauth/`](references/oauth/)
 
 **Features:**
 - OAuth2 authentication flow
 - JWT tokens
 - Protected MCP server endpoints
 - Pydantic AI agent integration
 
-See the [MCP Auth Example README](examples/mcp-auth/README.md) for details.
+See the [MCP Auth Example README](references/oauth/README.md) for details.
 
 ## 🗂️ Resources
 

docs/ARCHITECTURE.md

@@ -25,9 +25,12 @@ The MCP Compose exposes all the tools of the managed MCP Servers as a single uni
 A `Managed MCP Server` can be:
 
 - **`Embedded`**: Python packages that implement MCP servers using the Python MCP SDK. These are loaded in-process and configured via a manual list in `mcp_compose.toml`.
-- **`Proxied`**: External MCP servers accessible via `STDIO` or `SSE (Server-Sent Events)`. The startup commands and configurations for these proxied servers are defined in `mcp_compose.toml`.
+- **`Proxied`**: External MCP servers accessible via `STDIO`, `Streamable HTTP`, or `SSE (Server-Sent Events, deprecated)`. The startup commands and configurations for these proxied servers are defined in `mcp_compose.toml`.
 
-The supported exposed **transports** are the official MCP transports: `STDIO` and `SSE (Server-Sent Events)`.
+The supported exposed **transports** are the official MCP transports:
+- **STDIO**: For subprocess communication (agent spawns server)
+- **Streamable HTTP**: Modern HTTP-based transport (recommended for production)
+- **SSE (deprecated)**: Server-Sent Events for streaming (use Streamable HTTP instead)
 
 ## Component Architecture
 
@@ -38,7 +41,7 @@ The supported exposed **transports** are the official MCP transports: `STDIO` an
 │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐   │
 │  │    Authn     │  │    Authz     │  │    Transport       │   │
 │  │  Middleware  │  │  Middleware  │  │  Layer             │   │
-│  │              │  │              │  │  (STDIO/SSE)       │   │
+│  │              │  │              │  │ (STDIO/HTTP/SSE)   │   │
 │  └──────────────┘  └──────────────┘  └────────────────────┘   │
 ├───────────────────────────────────────────────────────────────┤
 │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐   │
@@ -50,7 +53,7 @@ The supported exposed **transports** are the official MCP transports: `STDIO` an
 │  Managed MCP Servers                                          │
 │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐   │
 │  │  Embedded    │  │   Proxied    │  │    Proxied         │   │
-│  │   Python     │  │   (STDIO)    │  │    (SSE)           │   │
+│  │   Python     │  │   (STDIO)    │  │   (HTTP/SSE)       │   │
 │  │  Packages    │  │              │  │                    │   │
 │  └──────────────┘  └──────────────┘  └────────────────────┘   │
 └───────────────────────────────────────────────────────────────┘
@@ -78,16 +81,24 @@ All configuration is managed through a single `mcp_compose.toml` file. The previ
 name = "my-unified-server"
 conflict_resolution = "prefix"  # prefix, suffix, ignore, error, override, custom
 log_level = "INFO"
-port = 8080  # For HTTP/SSE transport and REST API
+port = 8080  # For HTTP transport and REST API
 
 # ============================================================================
 # Transport Configuration
 # ============================================================================
 [transport]
+# STDIO transport - for subprocess communication
 stdio_enabled = true
-sse_enabled = true       # Server-Sent Events for streaming
-sse_path = "/sse"        # SSE endpoint path
-sse_cors_enabled = true  # Enable CORS for SSE
+
+# Streamable HTTP transport (recommended) - modern HTTP-based MCP transport
+streamable_http_enabled = true
+streamable_http_path = "/mcp"
+streamable_http_cors_enabled = true
+
+# SSE transport (deprecated) - use Streamable HTTP instead
+sse_enabled = false
+sse_path = "/sse"
+sse_cors_enabled = true
 
 # ============================================================================
 # Authentication Configuration
@@ -111,11 +122,32 @@ issuer = "mcp-composer"
 audience = "mcp-clients"
 
 # OAuth2/OIDC Authentication
+# Supports two modes:
+# 1. Generic token validation (validates bearer tokens via userinfo/introspection)
+# 2. OAuth2 authorization flow (for known providers like google, github, microsoft)
+
+# Example 1: Generic OAuth2 token validation (recommended for server-side auth)
 [authentication.oauth2]
-provider = "auth0"  # auth0, keycloak, custom
-client_id = "${OAUTH_CLIENT_ID}"
-client_secret = "${OAUTH_CLIENT_SECRET}"
-discovery_url = "${OAUTH_DISCOVERY_URL}"
+provider = "generic"  # Use generic for standard OAuth2/OIDC token validation
+issuer_url = "https://id.example.com"  # OIDC issuer for auto-discovery
+# Or explicit endpoints:
+# userinfo_endpoint = "https://id.example.com/userinfo"
+# introspection_endpoint = "https://id.example.com/oauth/introspect"
+client_id = "${OAUTH_CLIENT_ID}"        # Optional, for introspection
+client_secret = "${OAUTH_CLIENT_SECRET}"  # Optional, for introspection
+user_id_claim = "sub"                   # Claim to use for user identification
+# required_scopes = ["openid", "profile"]  # Optional scope requirements
+
+# Example 2: OAuth2 authorization flow (for client-side auth)
+# [authentication.oauth2]
+# provider = "github"  # google, github, microsoft, auth0
+# client_id = "${OAUTH_CLIENT_ID}"
+# client_secret = "${OAUTH_CLIENT_SECRET}"
+# redirect_uri = "http://localhost:8080/oauth/callback"
+# scopes = ["read:user"]
+
+# Legacy configuration (deprecated, use issuer_url instead)
+# discovery_url = "${OAUTH_DISCOVERY_URL}"
 
 # Mutual TLS Authentication
 [authentication.mtls]

docs/USER_GUIDE.md

@@ -21,7 +21,7 @@ MCP Compose is a comprehensive solution for managing and composing multiple Mode
 - **Web UI**: Modern web interface for management and monitoring
 - **REST API**: Full-featured API for programmatic control
 - **Real-time Monitoring**: Live logs, metrics, and status updates
-- **Protocol Translation**: Support for STDIO and SSE transports
+- **Protocol Translation**: Support for STDIO, Streamable HTTP, and SSE (deprecated) transports
 
 ### Who Should Use This?
 
@@ -150,7 +150,7 @@ The dashboard shows:
 
 Each server card shows:
 - Command and arguments
-- Transport type (STDIO/SSE)
+- Transport type (STDIO/Streamable HTTP/SSE)
 - Process ID (when running)
 - Uptime (formatted as hours and minutes)
 - Restart count
@@ -404,7 +404,7 @@ conflict_resolution = "prefix"        # Strategy for name conflicts
 name = "filesystem"                   # Unique server identifier
 command = "python"                    # Executable to run
 args = ["-m", "mcp_server_filesystem", "/data"]  # Command arguments
-transport = "stdio"                   # Transport type (stdio or sse)
+transport = "stdio"                   # Transport type (stdio, streamable-http, or sse)
 env = { DEBUG = "1" }                # Optional environment variables
 auto_start = true                    # Start automatically (default: true)
 ```
@@ -451,6 +451,79 @@ LOG_LEVEL = "INFO"
 CACHE_DIR = "/tmp/cache"
 ```
 
+### Authentication Configuration
+
+MCP Compose supports multiple authentication providers for securing access to your composed MCP servers.
+
+#### API Key Authentication
+
+```toml
+[authentication]
+enabled = true
+providers = ["api_key"]
+default_provider = "api_key"
+
+[authentication.api_key]
+header_name = "X-API-Key"
+keys = ["your-api-key-1", "your-api-key-2"]
+```
+
+Clients send the API key in the header:
+```bash
+curl -H "X-API-Key: your-api-key-1" http://localhost:8080/mcp
+```
+
+#### OAuth2/OIDC Authentication (Generic)
+
+For validating OAuth2 bearer tokens with any OIDC provider:
+
+```toml
+[authentication]
+enabled = true
+providers = ["oauth2"]
+default_provider = "oauth2"
+
+[authentication.oauth2]
+provider = "generic"
+# OIDC issuer URL for auto-discovery of endpoints
+issuer_url = "https://id.example.com"
+
+# Or provide explicit endpoints:
+# userinfo_endpoint = "https://id.example.com/userinfo"
+# introspection_endpoint = "https://id.example.com/oauth/introspect"
+
+# Claim to use for user identification (default: "sub")
+user_id_claim = "sub"
+
+# Optional: Client credentials for token introspection
+# client_id = "your-client-id"
+# client_secret = "your-client-secret"
+
+# Optional: Required scopes
+# required_scopes = ["openid", "profile"]
+```
+
+Clients send bearer tokens:
+```bash
+curl -H "Authorization: Bearer <oauth-token>" http://localhost:8080/mcp
+```
+
+#### Anaconda Authentication
+
+For validating tokens with Anaconda Cloud:
+
+```toml
+[authentication]
+enabled = true
+providers = ["anaconda"]
+default_provider = "anaconda"
+
+[authentication.anaconda]
+domain = "anaconda.com"
+```
+
+See the `examples/anaconda-token/` and `examples/anaconda-oauth/` directories for complete examples.
+
 ## Server Management
 
 ### Starting Servers

examples/README.md

@@ -8,4 +8,4 @@
 
 [![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
 
-# ✨ MCP Compose
+# ✨ MCP Compose Examples

examples/proxy-anaconda/.gitignore examples/anaconda-token/.gitignoreexamples/proxy-anaconda/.gitignore renamed to examples/anaconda-token/.gitignore

@@ -7,10 +7,10 @@
 The composer manages multiple MCP servers and exposes them through a unified endpoint.
 
 Features:
-- Connection to MCP Compose via SSE transport
+- Connection to MCP Compose via Streamable HTTP transport
 - Interactive CLI interface powered by pydantic-ai
 - Access to Calculator and Echo server tools through the composer
-- Uses Anthropic Claude Sonnet 4.5 model
+- Uses Anthropic Claude Sonnet 4 model
 
 Usage:
     # First start the composer server:
@@ -36,7 +36,7 @@
 # Pydantic AI imports
 try:
     from pydantic_ai import Agent
-    from pydantic_ai.mcp import MCPServerSSE
+    from pydantic_ai.mcp import MCPServerStreamableHTTP
     HAS_PYDANTIC_AI = True
 except ImportError:
     HAS_PYDANTIC_AI = False
@@ -104,20 +104,18 @@ def create_agent(model: str = "anthropic:claude-sonnet-4-0", server_url: str = "
     # Get Anaconda access token
     access_token = get_anaconda_token()
 
-    print(f"\n📡 Connecting to MCP Compose: {server_url}/sse")
+    print(f"\n📡 Connecting to MCP Compose: {server_url}/mcp")
     print("   Unified access to Calculator and Echo servers")
     print("   Using Anaconda bearer token authentication")
 
-    # Create MCP server connection with SSE transport and authentication
-    mcp_server = MCPServerSSE(
-        url=f"{server_url}/sse",
+    # Create MCP server connection with Streamable HTTP transport and authentication
+    mcp_server = MCPServerStreamableHTTP(
+        url=f"{server_url}/mcp",
         headers={
             "Authorization": f"Bearer {access_token}"
         },
-        # Increase read timeout for long-running tool calls
-        read_timeout=300.0,  # 5 minutes
-        # Allow retries for transient failures
-        max_retries=2
+        # Increase timeout for long-running tool calls
+        timeout=300.0,  # 5 minutes
     )
 
     print(f"\n🤖 Initializing Agent with {model}")
@@ -181,15 +179,15 @@ def main():
         async def list_tools(access_token: str):
             """List all tools available from the MCP server"""
             try:
-                # Import MCP SDK client
+                # Import MCP SDK client for streamable HTTP
                 from mcp import ClientSession
-                from mcp.client.sse import sse_client
+                from mcp.client.streamable_http import streamablehttp_client
 
-                # Connect using SSE client with authentication
-                async with sse_client(
-                    "http://localhost:8080/sse",
+                # Connect using Streamable HTTP client with authentication
+                async with streamablehttp_client(
+                    "http://localhost:8080/mcp",
                     headers={"Authorization": f"Bearer {access_token}"}
-                ) as (read, write):
+                ) as (read, write, _):
                     async with ClientSession(read, write) as session:
                         # Initialize the session
                         await session.initialize()