Add OAuth user context caching + Refresh external tokens

docs/guides/authentication.md

@@ -1185,6 +1185,89 @@ projects:
             # ... other GitHub config
 ```
 
+## User Context Caching
+
+MXCP caches user context information to improve performance and reduce load on OAuth providers. When a user is authenticated, their user information (username, email, provider details) is cached to avoid making API calls to the OAuth provider on every tool execution.
+
+### Cache TTL Configuration
+
+You can configure the cache duration using the `cache_ttl` setting:
+
+```yaml
+projects:
+  my_project:
+    profiles:
+      dev:
+        auth:
+          provider: github
+          cache_ttl: 300        # Cache user context for 5 minutes (default: 300 seconds)
+          cleanup_interval: 300 # OAuth cleanup interval in seconds (default: 300 seconds)
+
+          clients:
+            - client_id: "${CLIENT_ID}"
+              # ... client config
+```
+
+**Configuration Options:**
+
+- `cache_ttl`: Cache duration in seconds for user context information
+  - **Default**: 300 seconds (5 minutes)
+  - **Purpose**: Reduces API calls to OAuth providers, improving performance and avoiding rate limits
+  - **Range**: Any positive integer (recommended: 60-1800 seconds)
+
+- `cleanup_interval`: OAuth cleanup interval in seconds
+  - **Default**: 300 seconds (5 minutes)
+  - **Purpose**: Removes expired OAuth codes and orphaned mappings to prevent memory leaks
+  - **Range**: Any positive integer (recommended: 60-1800 seconds)
+
+**Security Considerations:**
+
+- Cached user context expires automatically after the TTL period
+- User information is cached in memory only (not persisted to disk)
+- Cache is cleared when the server restarts
+- Shorter TTL values provide more up-to-date user information but increase API calls
+
+## OAuth Cleanup Configuration
+
+MXCP automatically cleans up expired OAuth authorization codes and orphaned token mappings to prevent memory leaks. This cleanup process runs in the background and can be configured to suit your needs.
+
+### Cleanup Interval Configuration
+
+You can configure how often the OAuth cleanup process runs using the `cleanup_interval` setting:
+
+```yaml
+projects:
+  my_project:
+    profiles:
+      dev:
+        auth:
+          provider: github
+          cache_ttl: 300        # User context cache TTL
+          cleanup_interval: 300 # OAuth cleanup interval in seconds (default: 300)
+
+          clients:
+            - client_id: "${CLIENT_ID}"
+              # ... client config
+```
+
+**Configuration Options:**
+
+- `cleanup_interval`: How often to run OAuth cleanup in seconds
+  - **Default**: 300 seconds (5 minutes)
+  - **Purpose**: Removes expired authorization codes and orphaned token mappings to prevent memory leaks
+  - **Range**: Any positive integer (recommended: 60-1800 seconds)
+
+**What Gets Cleaned Up:**
+
+- **Expired authorization codes**: OAuth codes that have passed their 5-minute expiration time
+- **Orphaned token mappings**: External token mappings without corresponding authorization codes
+- **Orphaned refresh token mappings**: Refresh token mappings without corresponding authorization codes
+
+**Performance Considerations:**
+
+- The cleanup process is lightweight and runs asynchronously without blocking requests
+- Cleanup only runs when there are actually expired items to clean up
+
 ## Authorization Configuration
 
 MXCP supports configurable scope-based authorization to control access to your endpoints and tools. You can specify which OAuth scopes are required for accessing your server's resources.
@@ -1459,6 +1542,12 @@ auth:
 - URLs use HTTPS in production environments
 - No port numbers in URLs when using standard ports (80/443)
 
+**Memory usage concerns**: MXCP automatically cleans up OAuth-related memory:
+- Authorization codes expire after 5 minutes and are automatically cleaned up
+- Orphaned token mappings are removed by the background cleanup process
+- Adjust `cleanup_interval` to run cleanup more frequently if needed
+- User context cache is also automatically cleaned up based on `cache_ttl`
+
 ## Adding New Providers
 
 The authentication system is designed to be extensible. Future OAuth providers can be added by:

examples/keycloak/config.yml

@@ -1,4 +1,11 @@
 mxcp: 1
+transport:
+  http:
+    port: 8000
+    host: 0.0.0.0
+    # Set base_url to your server's public URL for production
+    base_url: http://localhost:8000
+
 projects:
   keycloak-demo:
     profiles:
@@ -17,10 +24,3 @@ projects:
             server_url: "${KEYCLOAK_SERVER_URL}"
             scope: "openid profile email"
             callback_path: "/keycloak/callback"
-          clients:
-            - client_id: "mcp-cli"
-              name: "MCP CLI Client"
-              redirect_uris:
-                - "http://127.0.0.1:49153/oauth/callback"
-              scopes:
-                - "mxcp:access" 

src/mxcp/sdk/auth/_types.py

@@ -133,6 +133,8 @@ class AuthConfig(TypedDict, total=False):
     """
 
     provider: Literal["none", "github", "atlassian", "salesforce", "keycloak", "google"] | None
+    cache_ttl: int | None  # Cache TTL in seconds for user context caching
+    cleanup_interval: int | None  # Cleanup interval in seconds for OAuth mappings (default: 300)
     clients: list[OAuthClientConfig] | None  # Pre-configured OAuth clients
     authorization: AuthorizationConfig | None  # Authorization policies
     persistence: AuthPersistenceConfig | None  # Token/client persistence
@@ -144,8 +146,9 @@ class ExternalUserInfo:
 
     id: str
     scopes: list[str]
-    raw_token: str  # original token from the IdP (JWT or opaque)
+    raw_token: str  # original access token from the IdP (JWT or opaque)
     provider: str
+    refresh_token: str | None = None  # refresh token for renewing access tokens
 
 
 @dataclass