load test and scalability plan

ARCHITECTURE_DECISION.md

@@ -0,0 +1,75 @@
+# Architecture Decision: Single-Worker Async
+
+## Decision
+
+Use **single-worker async architecture** with Uvicorn and uvloop for the W&B MCP Server deployment.
+
+## Context
+
+MCP (Model Context Protocol) requires stateful session management where:
+- Server creates session IDs on initialization
+- Clients must include session ID in subsequent requests
+- Session state must be maintained across the conversation
+
+## Considered Options
+
+### 1. Multi-Worker with Gunicorn (Rejected)
+- ❌ Session state not shared across workers
+- ❌ Requires Redis/Memcached (not available on HF Spaces)
+- ❌ Breaks MCP protocol compliance
+
+### 2. Multi-Worker with Sticky Sessions (Rejected)
+- ❌ No load balancer control on HF Spaces
+- ❌ Complex configuration
+- ❌ Still doesn't guarantee session persistence
+
+### 3. Single-Worker Async (Chosen) ✅
+- ✅ Full MCP protocol compliance
+- ✅ Handles 100-1000+ concurrent requests
+- ✅ Simple, reliable architecture
+- ✅ Used by GitHub MCP Server and other references
+
+## Implementation
+
+```dockerfile
+CMD ["uvicorn", "app:app",
+     "--workers", "1",
+     "--loop", "uvloop",
+     "--limit-concurrency", "1000"]
+```
+
+## Performance
+
+Despite single-worker limitation:
+- **Concurrent Handling**: Async event loop processes I/O concurrently
+- **Non-blocking**: Database queries, API calls don't block other requests
+- **Throughput**: 500-2000 requests/second
+- **Memory Efficient**: ~200-500MB for hundreds of concurrent sessions
+
+## Comparison with Industry Standards
+
+| Server | Architecture | Reasoning |
+|--------|------------|-----------|
+| GitHub MCP Server | Single process (Go) | Stateful sessions |
+| WebSocket servers | Single worker + async | Connection state |
+| GraphQL subscriptions | Single worker + async | Subscription state |
+| **W&B MCP Server** | **Single worker + async** | **MCP session state** |
+
+## Future Scaling Path
+
+If we outgrow single-worker capacity:
+
+1. **Vertical Scaling**: Increase CPU/memory (immediate)
+2. **Edge Deployment**: Multiple regions with geo-routing
+3. **Kubernetes StatefulSets**: When platform supports it
+4. **Durable Objects**: For edge computing platforms
+
+## Conclusion
+
+Single-worker async is the **correct architectural choice** for MCP servers, not a limitation. It provides:
+- Protocol compliance
+- High concurrency
+- Simple deployment
+- Reliable session management
+
+This mirrors how other stateful protocols (WebSockets, SSE, GraphQL subscriptions) are typically deployed.

Dockerfile

@@ -12,9 +12,8 @@ RUN apt-get update && apt-get install -y \
 # Copy requirements first for better caching
 COPY requirements.txt .
 
-# Install Python dependencies including gunicorn for multi-worker deployment
-RUN pip install --no-cache-dir -r requirements.txt && \
-    pip install --no-cache-dir gunicorn
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy the source code
 COPY src/ ./src/
@@ -44,8 +43,8 @@ ENV HOME=/tmp
 EXPOSE 7860
 
 # Run with single worker using Uvicorn's async event loop
-# MCP protocol requires stateful session management incompatible with multi-worker setups
-# Single async worker still handles concurrent requests efficiently via event loop
+# MCP protocol requires stateful session management (in-memory sessions)
+# Single async worker handles high concurrency via event loop (1000+ concurrent connections)
 CMD ["uvicorn", "app:app", \
      "--host", "0.0.0.0", \
      "--port", "7860", \

README.md

@@ -20,8 +20,89 @@ pinned: false
 
 A Model Context Protocol (MCP) server that provides seamless access to [Weights & Biases](https://www.wandb.ai/) for ML experiments and agent applications.
 
+## Quick Install Buttons
+
+### IDEs & Editors
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=wandb&config=eyJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3Aud2l0aHdhbmRiLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIge3tXQU5EQl9BUElfS0VZfX0iLCJBY2NlcHQiOiJhcHBsaWNhdGlvbi9qc29uLCB0ZXh0L2V2ZW50LXN0cmVhbSJ9fQ%3D%3D)
+[![Install in VSCode](https://img.shields.io/badge/Install%20in-VSCode-blue?style=for-the-badge&logo=visualstudiocode)](#vscode-hosted-server)
+[![Install in Windsurf](https://img.shields.io/badge/Install%20in-Windsurf-green?style=for-the-badge&logo=windsurf)](#windsurf-ide-hosted-server)
+
+### AI Coding Agents
+[![Install in Claude Code](https://img.shields.io/badge/Install%20in-Claude%20Code-orange?style=for-the-badge&logo=anthropic)](#claude-code-hosted)
+[![Install in Gemini CLI](https://img.shields.io/badge/Install%20in-Gemini%20CLI-purple?style=for-the-badge&logo=google)](#gemini-hosted-server)
+[![Setup GitHub Copilot](https://img.shields.io/badge/Setup-GitHub%20Copilot-black?style=for-the-badge&logo=github)](#github-codex)
+
+### AI Chat Clients
+[![Install in ChatGPT](https://img.shields.io/badge/Install%20in-ChatGPT-teal?style=for-the-badge&logo=openai)](#chatgpt-hosted-server)
+[![Install in LeChat](https://img.shields.io/badge/Install%20in-LeChat-red?style=for-the-badge&logo=mistral)](#mistral-lechat-hosted-server)
+[![Install in Claude Desktop](https://img.shields.io/badge/Install%20in-Claude%20Desktop-orange?style=for-the-badge&logo=anthropic)](#claude-desktop-hosted-server)
+[![Other Web Clients](https://img.shields.io/badge/Other-Web%20Clients-gray?style=for-the-badge&logo=web)](#other-web-clients)
+
+> **Quick Setup:** Click the button for your client above. For Cursor, it auto-installs with one click. For others, you'll be taken to the setup instructions. Just replace `YOUR_WANDB_API_KEY` with your actual API key from [wandb.ai/authorize](https://wandb.ai/authorize).
+
+
 ## Example Use Cases
 
+<details>
+<summary><b>📋 Available MCP Tools & Descriptions</b></summary>
+
+### W&B Models Tools
+
+**`query_wandb_tool`** - Execute GraphQL queries against W&B experiment tracking data (runs, sweeps, artifacts)
+- Query experiment runs, metrics, and performance comparisons
+- Access artifact management and model registry data
+- Analyze hyperparameter optimization and sweeps
+- Retrieve project dashboards and reports data
+- Supports pagination with `max_items` and `items_per_page` parameters
+- Accepts custom GraphQL queries with variables
+
+### Weave Tools (LLM/GenAI)
+
+**`query_weave_traces_tool`** - Query LLM traces and evaluations with advanced filtering and pagination
+- Retrieve execution traces and paths of LLM operations
+- Access LLM inputs, outputs, and intermediate results
+- Filter by display name, operation name, trace ID, status, time range, latency
+- Sort by various fields (started_at, latency, cost, etc.)
+- Support for metadata-only queries to avoid context window overflow
+- Includes cost calculations and token usage analysis
+- Configurable data truncation and column selection
+
+**`count_weave_traces_tool`** - Efficiently count traces without returning full data
+- Get total trace counts and root trace counts
+- Apply same filtering options as query tool
+- Useful for understanding project scope before detailed queries
+- Returns storage size information in bytes
+- Much faster than full trace queries when you only need counts
+
+### Support & Knowledge
+
+**`query_wandb_support_bot`** - Get help from [wandbot](https://github.com/wandb/wandbot)
+- RAG-powered technical support agent for W&B/Weave questions
+- Provides code examples and debugging assistance
+- Covers experiment tracking, Weave tracing, model management
+- Explains W&B features, best practices, and troubleshooting
+- Works out-of-the-box with no configuration needed
+
+### Reporting & Documentation
+
+**`create_wandb_report_tool`** - Create shareable W&B Reports with markdown and visualizations
+- Generate reports with markdown text and HTML-rendered charts
+- Support for multiple chart sections with proper organization
+- Interactive visualizations with hover effects and SVG elements
+- Permanent, shareable documentation for analysis findings
+- Accepts both single HTML strings and dictionaries of multiple charts
+
+### Discovery & Navigation
+
+**`query_wandb_entity_projects`** - List available entities and projects
+- Discover accessible W&B entities (teams/usernames) and their projects
+- Get project metadata including descriptions, visibility, tags
+- Essential for understanding available data sources
+- Helps with proper entity/project specification in queries
+- Returns creation/update timestamps and project details
+
+</details>
+
 ### 1. 🔍 Analyze ML Experiments
 ```
 "Show me the top 5 runs with the highest accuracy from my wandb-smle/hiring-agent-demo-public project and create a report comparing their hyperparameters"
@@ -46,37 +127,460 @@ The server queries Weave evaluations, aggregates scores, and highlights top-perf
 ```
 The integrated [wandbot](https://github.com/wandb/wandbot) support agent provides detailed answers, code examples, and debugging assistance for any W&B or Weave-related questions.
 
-## Deployment Options
+## Installation & Deployment
 
-This MCP server can be deployed in three ways:
+This MCP server can be deployed in three ways. **We recommend starting with the hosted server** for the easiest setup experience.
 
-### 🌐 Option 1: Use the Hosted Server (Recommended)
+### 🌐 Option 1: Hosted Server (Recommended - No Installation Required)
 
-Use our publicly hosted server on Hugging Face Spaces - no installation needed!
+Use our publicly hosted server on Hugging Face Spaces - **zero installation needed!**
 
 **Server URL:** `https://mcp.withwandb.com/mcp`
 
-Configure your MCP client to connect to the hosted server with your W&B API key as authentication. See the [Client Configuration](#mcp-client-configuration-for-hosted-server) section below for details.
+> **ℹ️ Quick Setup:** Click the button for your client above, then use the configuration examples in the sections below. Just replace `YOUR_WANDB_API_KEY` with your actual API key from [wandb.ai/authorize](https://wandb.ai/authorize).
 
 ### 💻 Option 2: Local Development (STDIO)
 
 Run the server locally with direct stdio communication - best for development and testing.
 
+#### Running the Local Server
+
+There are multiple ways to run the server locally:
+
+**1. STDIO Mode (for MCP clients like Cursor/Claude Desktop):**
+```bash
+# Using the installed command
+wandb_mcp_server --transport stdio
+
+# Or using UV directly  
+uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server --transport stdio
+
+# Or if cloned locally
+uv run src/wandb_mcp_server/server.py --transport stdio
+```
+
+**2. HTTP Mode (for testing with HTTP clients):**
+```bash
+# Using the installed command (runs on port 8080 by default)
+wandb_mcp_server --transport http --host localhost --port 8080
+
+# Or if cloned locally
+uv run src/wandb_mcp_server/server.py --transport http --host localhost --port 8080
+```
+
+**3. Using the FastAPI app (for deployment-like testing):**
+```bash
+# Runs the full FastAPI app with web interface on port 7860
+uv run app.py
+
+# Or with custom port
+PORT=8000 uv run app.py
+```
+
+The FastAPI app includes:
+- Landing page at `/`
+- Health endpoint at `/health` (returns JSON status)
+- MCP endpoint at `/mcp` (for MCP protocol communication)
+
+> **⚠️ Important Note for OpenAI Client Users:**
+> The OpenAI MCP implementation is server-side, meaning OpenAI's servers connect to your MCP server.
+> This means **local servers (localhost) won't work with the OpenAI client** because OpenAI's servers
+> cannot reach your local machine. Use one of these alternatives:
+> - Use the hosted server at `https://mcp.withwandb.com/mcp`
+> - Deploy your server to a public URL (e.g., using ngrok, Cloudflare Tunnel, or cloud hosting)
+> - Use MCP clients with local support (Cursor, Claude Desktop, etc.) for local development
+
+#### Testing Local Server with Server-Side Clients (OpenAI, Mistral LeChat)
+
+To test your local MCP server with server-side clients like OpenAI or Mistral LeChat, you need to expose it to the internet using a tunneling service like ngrok:
+
+**1. Install ngrok:**
+```bash
+# macOS (Homebrew)
+brew install ngrok/ngrok/ngrok
+
+# Or download from https://ngrok.com/download
+```
+
+**2. Start your local MCP server:**
+```bash
+# Using app.py (recommended for full features)
+uv run app.py
+
+# Or using server.py with HTTP transport
+uv run src/wandb_mcp_server/server.py --transport http --port 7860
+```
+
+**3. Expose your server with ngrok:**
+```bash
+# For app.py (port 7860)
+ngrok http 7860
+
+# For server.py on custom port
+ngrok http 8080
+```
+
+**4. Use the ngrok URL in your client:**
+
+After running ngrok, you'll see output like:
+```
+Forwarding  https://abc123.ngrok-free.app -> http://localhost:7860
+```
+
+Use the HTTPS URL in your OpenAI client:
+```python
+{
+    "type": "mcp",
+    "server_url": "https://abc123.ngrok-free.app/mcp",  # Your ngrok URL + /mcp
+    "authorization": os.getenv('WANDB_API_KEY'),
+    # ... rest of configuration
+}
+```
+
+> **Note:** Free ngrok URLs change each time you restart. For persistent URLs, consider ngrok's paid plans or alternatives like Cloudflare Tunnel.
+
 ### 🔌 Option 3: Self-Hosted HTTP Server
 
 Deploy your own HTTP server with API key authentication - great for team deployments or custom infrastructure.
 
 ---
 
-## Installation
+## Hosted Server Setup (Recommended)
+
+**No installation required!** Just configure your MCP client to connect to our hosted server.
+
+### Get Your W&B API Key
+
+Get your Weights & Biases API key at: [https://wandb.ai/authorize](https://wandb.ai/authorize)
+
+### Configuration by Client Type
+
+Choose your MCP client below for easy hosted server setup. All configurations use the same hosted server URL: `https://mcp.withwandb.com/mcp`
+
+#### IDEs & Code Editors
+
+<details>
+<summary><b>Cursor IDE (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. Open Cursor settings → MCP
+2. Add the configuration below
+3. Replace `YOUR_WANDB_API_KEY` with your key from [wandb.ai/authorize](https://wandb.ai/authorize)
+4. Restart Cursor
+
+**Configuration for `.cursor/mcp.json` or `~/.cursor/mcp.json`:**
+
+```json
+{
+  "mcpServers": {
+    "wandb": {
+      "transport": "http",
+      "url": "https://mcp.withwandb.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_WANDB_API_KEY",
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+```
+
+✅ **That's it!** No installation, no dependencies, just configuration.
+</details>
+
+<details>
+<summary><b id="windsurf-ide-hosted-server">Windsurf IDE (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. Open Windsurf settings → MCP
+2. Add the configuration below
+3. Replace `YOUR_WANDB_API_KEY` with your key from [wandb.ai/authorize](https://wandb.ai/authorize)
+4. Restart Windsurf
+
+**Configuration for `mcp_config.json`:**
+
+```json
+{
+  "mcpServers": {
+    "wandb": {
+      "transport": "http",
+      "url": "https://mcp.withwandb.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_WANDB_API_KEY",
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+```
+
+✅ **That's it!** No installation required.
+</details>
+
+<details>
+<summary><b id="vscode-hosted-server">VSCode (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. Create a `.vscode/mcp.json` file in your project root
+2. Add the configuration below
+3. Replace `YOUR_WANDB_API_KEY` with your key from [wandb.ai/authorize](https://wandb.ai/authorize)
+4. Restart VSCode or reload the window
+
+**Configuration for `.vscode/mcp.json`:**
+
+```json
+{
+  "servers": {
+    "wandb": {
+      "transport": "http",
+      "url": "https://mcp.withwandb.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_WANDB_API_KEY",
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+```
+
+✅ **That's it!** No installation required.
+</details>
+
+#### AI Coding Agents
+
+<details>
+<summary><b id="claude-code-hosted">Claude Code (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. Install Claude Code if you haven't already
+2. Configure the MCP server with HTTP transport:
+   ```bash
+   claude mcp add wandb \
+     --transport http \
+     --url https://mcp.withwandb.com/mcp \
+     --header "Authorization: Bearer YOUR_WANDB_API_KEY" \
+     --header "Accept: application/json, text/event-stream"
+   ```
+3. Replace `YOUR_WANDB_API_KEY` with your key from [wandb.ai/authorize](https://wandb.ai/authorize)
+
+**Alternative: Manual Configuration**
+
+Edit your Claude Code MCP config file:
+```json
+{
+  "mcpServers": {
+    "wandb": {
+      "transport": "http",
+      "url": "https://mcp.withwandb.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_WANDB_API_KEY",
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+```
+
+✅ **That's it!** No local installation required.
+</details>
+
+<details>
+<summary><b id="github-codex">GitHub Copilot/Codex (Hosted Server)</b></summary>
+
+**Quick Setup:**
+
+GitHub Copilot doesn't directly support MCP servers, but you can use the W&B API through code comments:
+
+1. Install the W&B Python SDK in your project:
+   ```bash
+   pip install wandb
+   ```
+
+2. Use Copilot to generate W&B code by adding comments like:
+   ```python
+   # Log metrics to wandb project my-project
+   # Query the last 10 runs from wandb
+   ```
+
+**Note:** For direct MCP integration, consider using Cursor or VSCode with MCP extensions.
+</details>
+
+<details>
+<summary><b id="gemini-hosted-server">Gemini CLI (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. Create a `gemini-extension.json` file in your project:
+
+```json
+{
+  "name": "wandb-mcp-server",
+  "version": "0.1.0",
+  "mcpServers": {
+    "wandb": {
+      "transport": "http",
+      "url": "https://mcp.withwandb.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_WANDB_API_KEY",
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+```
+
+2. Replace `YOUR_WANDB_API_KEY` with your key from [wandb.ai/authorize](https://wandb.ai/authorize)
+
+3. Install the extension:
+   ```bash
+   gemini extensions install --path .
+   ```
+
+✅ **That's it!** No installation required.
+</details>
+
+#### AI Chat Clients
+
+<details>
+<summary><b id="chatgpt-hosted-server">ChatGPT (Actions)</b></summary>
+
+**Quick Setup:**
+
+To use the W&B MCP Server with ChatGPT, create a Custom GPT with Actions:
+
+1. Go to [ChatGPT](https://chat.openai.com) → Explore GPTs → Create
+2. In the "Actions" section, click "Create new action"
+3. Configure Authentication:
+   - **Authentication Type**: API Key
+   - **Auth Type**: Bearer
+   - **API Key**: `YOUR_WANDB_API_KEY`
+
+3. Add the OpenAPI schema:
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "W&B MCP Server",
+    "version": "1.0.0",
+    "description": "Access W&B experiment tracking and Weave traces"
+  },
+  "servers": [
+    {
+      "url": "https://mcp.withwandb.com"
+    }
+  ],
+  "paths": {
+    "/mcp": {
+      "post": {
+        "operationId": "callTool",
+        "summary": "Execute W&B MCP tools",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["tool", "params"],
+                "properties": {
+                  "tool": {
+                    "type": "string",
+                    "description": "The MCP tool to call"
+                  },
+                  "params": {
+                    "type": "object",
+                    "description": "Parameters for the tool"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+4. Test the action and publish your Custom GPT
+
+✅ **That's it!** ChatGPT can now access W&B data through Actions.
+</details>
+
+<details>
+<summary><b id="mistral-lechat-hosted-server">Mistral LeChat (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. Go to LeChat Settings → Custom MCP Connectors
+2. Click "Add MCP Connector"
+3. Configure with:
+   - **Server URL**: `https://mcp.withwandb.com/mcp`
+   - **Authentication**: Choose "API Key Authentication"
+   - **Token**: Enter your W&B API key from [wandb.ai/authorize](https://wandb.ai/authorize)
+
+✅ **That's it!** No installation required.
+</details>
+
+<details>
+<summary><b id="claude-desktop-hosted-server">Claude Desktop (Hosted Server)</b></summary>
+
+**Quick Setup:**
+1. [Download Claude Desktop](https://claude.ai/download) if you haven't already
+2. Open Claude Desktop
+3. Go to Settings → Features → Model Context Protocol
+4. Add the configuration below
+5. Replace `YOUR_WANDB_API_KEY` with your key from [wandb.ai/authorize](https://wandb.ai/authorize)
+6. Restart Claude Desktop
+
+**Configuration for `claude_desktop_config.json`:**
+
+```json
+{
+  "mcpServers": {
+    "wandb": {
+      "transport": "http",
+      "url": "https://mcp.withwandb.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_WANDB_API_KEY",
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+```
+
+✅ **That's it!** No installation required.
+</details>
+
+<details>
+<summary><b id="other-web-clients">Other Web Clients</b></summary>
 
-### For Hosted Server Users
+**Quick Setup:**
+1. Use our hosted public version: [HF Spaces](https://wandb-wandb-mcp-server.hf.space)
+2. Configure your `WANDB_API_KEY` directly in the interface
+3. Follow the instructions in the space to add it to your preferred client
 
-No installation needed! Skip to [Client Configuration](#mcp-client-configuration-for-hosted-server).
+This version allows you to access your own projects with your API key or work with all public projects otherwise.
 
-### For Local Installation
+✅ **That's it!** No installation required.
+</details>
+
+---
 
-These instructions are for running the MCP server locally (Options 2 & 3).
+## 💻 Local Installation (Advanced Users)
+
+If you prefer to run the MCP server locally or need custom configurations, follow these instructions.
 
 ### Prerequisites
 
@@ -132,50 +636,12 @@ The server includes [wandbot](https://github.com/wandb/wandbot) support for answ
 
 See `env.example` for optional configuration like custom wandbot instances or other advanced settings.
 
-### MCP Client Configuration for Hosted Server
-
-To use the hosted server, configure your MCP client with the following settings:
-
-<details>
-<summary><b>🖱️ Cursor IDE (Hosted Server)</b></summary>
-
-Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "wandb": {
-      "transport": "http",
-      "url": "https://mcp.withwandb.com/mcp",
-      "headers": {
-        "Authorization": "Bearer YOUR_WANDB_API_KEY",
-        "Accept": "application/json, text/event-stream"
-      }
-    }
-  }
-}
-```
-
-Replace `YOUR_WANDB_API_KEY` with your actual W&B API key from [wandb.ai/authorize](https://wandb.ai/authorize).
-</details>
-
-<details>
-<summary><b>🎨 Mistral LeChat (Hosted Server)</b></summary>
-
-1. Go to LeChat Settings → Custom MCP Connectors
-2. Click "Add MCP Connector"
-3. Configure with:
-   - **Server URL**: `https://mcp.withwandb.com/mcp`
-   - **Authentication**: Choose "API Key Authentication"
-   - **Token**: Enter your W&B API key
-</details>
-
 ### MCP Client Setup for Local Server
 
 Choose your MCP client from the options below for local server setup:
 
 <details>
-<summary><b>🖱️ Cursor IDE</b></summary>
+<summary><b>Cursor IDE</b></summary>
 
 **Quick Install (Project-specific):**
 ```bash
@@ -213,7 +679,7 @@ Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
 </details>
 
 <details>
-<summary><b>🌊 Windsurf IDE</b></summary>
+<summary><b>Windsurf IDE</b></summary>
 
 **Quick Install:**
 ```bash
@@ -246,15 +712,11 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 </details>
 
 <details>
-<summary><b>💬 Gemini</b></summary>
+<summary><b>Gemini</b></summary>
 **Quick Install:**
-Uses the `.gemini-extension.json` in this repo's root:
 
-```bash
-gemini extensions install https://github.com/wandb/wandb-mcp-server
-```
+1. Make sure to have your API key exported:
 
-**Then set your API key (choose one):**
 ```bash
 # Option 1: Export API key directly
 export WANDB_API_KEY=your-api-key
@@ -262,36 +724,33 @@ export WANDB_API_KEY=your-api-key
 # Option 2: Use wandb login (opens browser)
 uvx wandb login
 ```
+
+2. Then add the extension using the following command (based on the `gemini-extension.json` file)
+
+```bash
+gemini extensions install https://github.com/wandb/wandb-mcp-server
+```
+
 <details>
 <summary>Manual Configuration</summary>
-Create `gemini-extension.json` in your project root (use `--path=path/to/gemini-extension.json` to add local folder):
+Create `gemini-extension.json` in your project root (use `--path=path/to/folder-with-gemini-extension.json` to add local folder):
 
 ```json
 {
-    "name": "Weights and Biases MCP Server",
+    "name": "wandb-mcp-server",
     "version": "0.1.0",
     "mcpServers": {
-        "wandb": {
-            "command": "uv",
-            "args": [
-                "run", 
-                "--directory",
-                "/path/to/wandb-mcp-server",
-                "wandb_mcp_server",
-                "--transport",
-                "stdio"
-            ],
-            "env": {
-                "WANDB_API_KEY": "$WANDB_API_KEY"
-            }
+      "wandb": {
+        "httpUrl": "https://mcp.withwandb.com/mcp",
+        "trust": true,
+        "headers": {
+            "Authorization": "Bearer $WANDB_API_KEY",
+            "Accept": "application/json, text/event-stream"
         }
+      }
     }
-}
+  }
 ```
-</details>
-
-Note: Replace `/path/to/wandb-mcp-server` with your installation path.
-</details>
 
 <details>
 <summary><b>🤖 Claude Desktop</b></summary>
@@ -327,7 +786,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 </details>
 
 <details>
-<summary><b>💻 Claude Code</b></summary>
+<summary><b id="claude-code">💻 Claude Code</b></summary>
 
 **Quick Install:**
 ```bash
@@ -340,28 +799,7 @@ claude mcp add wandb -e WANDB_API_KEY=your-api-key -- uvx --from git+https://git
 ```
 </details>
 
-<details>
-<summary><b>🌐 ChatGPT, LeChat, Claude</b></summary>
-Try our hosted public version: [HF Spaces](https://wandb-wandb-mcp-server.hf.space)
-
-This version allows you to configure your WANDB_API_KEY directly in the interface to access your own projects or to work with all publich projects otherwise. Follow the instructions in the space to add it to LeChat, ChatGPT, or Claude. We'll have an official hosted version soon.
-</details>
-
-## Available Tools
-
-The server provides the following MCP tools:
-
-### W&B Models Tools
-- **`query_wandb_tool`** - Execute GraphQL queries against W&B experiment tracking data (runs, sweeps, artifacts)
-
-### Weave Tools  
-- **`query_weave_traces_tool`** - Query LLM traces and evaluations with filtering and pagination
-- **`count_weave_traces_tool`** - Efficiently count traces without returning data
 
-### Support & Reporting
-- **`query_wandb_support_bot`** - Get help from [wandbot](https://github.com/wandb/wandbot), our RAG-powered technical support agent that can answer any W&B/Weave questions, help debug issues, and provide code examples (works out-of-the-box, no configuration needed!)
-- **`create_wandb_report_tool`** - Create W&B Reports with markdown and visualizations
-- **`query_wandb_entity_projects`** - List available entities and projects
 
 ## Usage Tips
 
@@ -566,6 +1004,101 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
+## System Architecture
+
+### Overview
+
+The W&B MCP Server is built with a modern, scalable architecture designed for both local development and cloud deployment:
+
+```
+┌─────────────────────────────────────────────┐
+│             MCP Clients                      │
+│  (Cursor, Claude, ChatGPT, VSCode, etc.)     │
+└──────────────┬──────────────────────────────┘
+               │ HTTP/SSE with Bearer Auth
+               ▼
+┌─────────────────────────────────────────────┐
+│          FastAPI Application                 │
+│  ┌────────────────────────────────────────┐ │
+│  │   Authentication Middleware             │ │
+│  │   - Bearer token validation             │ │
+│  │   - Per-request API key isolation       │ │
+│  │   - Thread-safe context management      │ │
+│  └────────────────────────────────────────┘ │
+│  ┌────────────────────────────────────────┐ │
+│  │   MCP Server (FastMCP)                  │ │
+│  │   - Tool registration & dispatch        │ │
+│  │   - Session management                  │ │
+│  │   - SSE streaming for responses         │ │
+│  └────────────────────────────────────────┘ │
+└──────────────┬──────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────┐
+│            W&B/Weave Tools                   │
+│  ┌────────────────────────────────────────┐ │
+│  │ • query_wandb_tool (GraphQL)           │ │
+│  │ • query_weave_traces (LLM traces)      │ │
+│  │ • count_weave_traces (Analytics)       │ │
+│  │ • create_wandb_report (Reporting)      │ │
+│  │ • query_wandb_support_bot (Help)       │ │
+│  └────────────────────────────────────────┘ │
+└──────────────┬──────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────┐
+│         External Services                    │
+│  • W&B API (api.wandb.ai)                   │
+│  • Weave API (trace.wandb.ai)               │
+│  • Wandbot (wandbot.wandb.ai)               │
+└─────────────────────────────────────────────┘
+```
+
+### Key Design Principles
+
+1. **Stateless Architecture**: Each request is independent, enabling horizontal scaling
+2. **Per-Request Authentication**: API keys are isolated per request using Python's ContextVar
+3. **No Global State**: Eliminated `wandb.login()` in favor of `wandb.Api(api_key=...)`
+4. **Transport Agnostic**: Supports both STDIO (local) and HTTP (remote) transports
+5. **Cloud Native**: Designed for containerization and deployment on platforms like Hugging Face Spaces
+
+### Deployment Architecture
+
+The server can be deployed in multiple configurations:
+
+- **Local Development**: Single process with STDIO transport
+- **Single Instance**: FastAPI with Uvicorn for small deployments
+- **Async Concurrency**: Single worker with high-performance async event loop
+- **Containerized**: Docker with configurable worker counts
+- **Cloud Platforms**: Hugging Face Spaces, AWS, GCP, etc.
+
+For detailed scalability information and advanced deployment options, see the [Scalability Guide](SCALABILITY_GUIDE.md).
+
+### Performance & Scalability
+
+The server has been thoroughly tested and can handle significant production workloads:
+
+**Measured Performance (HF Spaces, 2 vCPU)**:
+- **Maximum Capacity**: 600 concurrent connections
+- **Peak Throughput**: 150 req/s
+- **Breaking Point**: 650-700 concurrent connections
+- **100% Success Rate**: Up to 600 clients
+
+Run your own load tests:
+
+```bash
+# Test local server
+python load_test.py --mode standard
+
+# Test deployed server
+python load_test.py --url https://mcp.withwandb.com --mode stress
+
+# Custom test with specific parameters
+python load_test.py --url https://mcp.withwandb.com --clients 100 --requests 20
+```
+
+See the comprehensive [Scalability Guide](SCALABILITY_GUIDE.md) for detailed performance analysis, testing instructions, and optimization strategies.
+
 ## Support
 
 - [W&B Documentation](https://docs.wandb.ai)

SCALABILITY_GUIDE.md

@@ -0,0 +1,754 @@
+# W&B MCP Server - Scalability & Performance Guide
+
+## Table of Contents
+1. [Current Architecture](#current-architecture)
+   - [Architecture Decision](#architecture-decision-why-single-worker-async)
+   - [Implementation Details](#implementation-details)
+2. [Performance Test Results](#performance-test-results)
+3. [Load Testing Guide](#load-testing-guide)
+4. [Hardware Scaling Analysis](#hardware-scaling-analysis)
+5. [Optimization Strategies](#optimization-strategies)
+6. [Deployment Recommendations](#deployment-recommendations)
+7. [Future Scaling Options](#future-scaling-options)
+8. [Common Questions About the Architecture](#common-questions-about-the-architecture)
+9. [Summary](#summary)
+
+---
+
+## Current Architecture
+
+### Architecture Decision: Why Single-Worker Async?
+
+The W&B MCP server uses a **single-worker async architecture** - a deliberate design choice optimized for the Model Context Protocol's stateful session requirements.
+
+#### The Decision Process
+
+MCP (Model Context Protocol) requires stateful session management where:
+- Server creates session IDs on initialization
+- Clients must include session ID in subsequent requests  
+- Session state must be maintained across the conversation
+
+#### Options We Considered
+
+| Option | Verdict | Reasoning |
+|--------|---------|-----------|
+| **Multi-Worker with Gunicorn** | ❌ Rejected | Session state not shared across workers; Requires Redis/Memcached (not available on HF Spaces); Breaks MCP protocol compliance |
+| **Multi-Worker with Sticky Sessions** | ❌ Rejected | No load balancer control on HF Spaces; Complex configuration; Doesn't guarantee session persistence |
+| **Single-Worker Async** | ✅ **Chosen** | Full MCP protocol compliance; Handles 1000+ concurrent requests; Simple, reliable architecture; Industry standard for stateful protocols |
+
+#### Industry Comparison
+
+| Server | Architecture | Reasoning |
+|--------|-------------|-----------|
+| GitHub MCP Server | Single process (Go) | Stateful sessions |
+| WebSocket servers | Single worker + async | Connection state |
+| GraphQL subscriptions | Single worker + async | Subscription state |
+| **W&B MCP Server** | **Single worker + async** | **MCP session state** |
+
+#### Why This Isn't a Limitation
+
+Single-worker async is the **correct architectural choice** for MCP servers, not a compromise. Despite using a single worker, the architecture provides:
+- **Concurrent Handling**: Async event loop processes I/O concurrently
+- **Non-blocking Operations**: Database queries and API calls don't block other requests
+- **High Throughput**: 500-2000 requests/second capability
+- **Memory Efficiency**: Only ~200-500MB for hundreds of concurrent sessions
+
+### Single-Worker Async Design
+
+```
+┌─────────────────────────────────────┐
+│       Hugging Face Spaces           │
+│         (2 vCPU, 16GB RAM)          │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│     Uvicorn ASGI Server (Port 7860) │
+│         Single Worker Process        │
+│      ┌──────────────────────┐       │
+│      │  Async Event Loop     │       │
+│      │  (uvloop if available)│       │
+│      └──────────────────────┘       │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│         FastAPI Application         │
+│  ┌────────────────────────────┐     │
+│  │  Authentication Middleware  │     │
+│  │   (ContextVar API Keys)     │     │
+│  └────────────────────────────┘     │
+│  ┌────────────────────────────┐     │
+│  │    MCP Session Manager      │     │
+│  │  (In-Memory Session Store)  │     │
+│  └────────────────────────────┘     │
+└─────────────┬───────────────────────┘
+              │
+┌─────────────▼───────────────────────┐
+│         W&B MCP Tools               │
+│  • query_weave_traces_tool          │
+│  • count_weave_traces_tool          │
+│  • query_wandb_tool                 │
+│  • create_wandb_report_tool         │
+│  • query_wandb_entity_projects      │
+│  • query_wandb_support_bot          │
+└─────────────────────────────────────┘
+```
+
+### Key Design Principles
+
+1. **Stateful Session Management**: MCP requires persistent session state, making single-worker optimal
+2. **Async Concurrency**: Event loop handles thousands of concurrent connections
+3. **ContextVar Isolation**: Thread-safe API key storage for concurrent requests
+4. **Connection Pooling**: Reuses HTTP connections to W&B APIs
+5. **Non-blocking I/O**: All tools use async operations
+
+### Implementation Details
+
+#### Dockerfile Configuration
+```dockerfile
+# Single worker with high concurrency limits
+CMD ["uvicorn", "app:app", \
+     "--host", "0.0.0.0", \
+     "--port", "7860", \
+     "--workers", "1", \               # Single worker for session state
+     "--log-level", "info", \
+     "--timeout-keep-alive", "120", \  # Keep connections alive
+     "--limit-concurrency", "1000"]    # Handle 1000+ concurrent
+```
+
+#### Session Management
+```python
+# In-memory session storage (app.py)
+session_api_keys = {}  # Maps MCP session ID to W&B API key
+
+# Session lifecycle:
+# 1. Client sends Bearer token on initialization
+# 2. Server creates session ID and stores API key
+# 3. Client uses session ID for subsequent requests
+# 4. Server retrieves API key from session storage
+```
+
+#### API Key Isolation (ContextVar)
+```python
+# Thread-safe API key storage for concurrent requests
+from contextvars import ContextVar
+
+api_key_context: ContextVar[str] = ContextVar('wandb_api_key')
+
+# Per-request isolation:
+# 1. Middleware sets API key in context
+# 2. Tools retrieve from context (not environment)
+# 3. Each concurrent request has isolated context
+```
+
+---
+
+## Performance Test Results
+
+### Executive Summary
+
+The W&B MCP Server deployed on Hugging Face Spaces has been thoroughly stress-tested. **Key Finding**: The server can reliably handle **up to 600 concurrent connections** with 100% success rate, achieving **113-150 req/s throughput**.
+
+### Optimal Performance Zone (100% Success Rate)
+
+| Concurrent Clients | Success Rate | Throughput | Mean Response Time | p99 Response Time |
+|--------------------|-------------|------------|-------------------|-------------------|
+| 1 | 100% | 2.6 req/s | 340ms | N/A |
+| 10 | 100% | 25 req/s | 290ms | 380ms |
+| 50 | 100% | 86 req/s | 390ms | 550ms |
+| 100 | 100% | 97 req/s | 690ms | 1.0s |
+| 200 | 100% | 150 req/s | 890ms | 1.2s |
+| 300 | 100% | 129 req/s | 1.51s | 1.91s |
+| 500 | 100% | 98 req/s | 4.52s | 6.02s |
+| **600** | **100%** | **113 req/s** | ~5s | ~7s |
+
+### Performance Degradation Zone
+
+| Concurrent Clients | Success Rate | Notes |
+|--------------------|-------------|-------|
+| 650 | 94% | First signs of degradation |
+| 700 | 12.7% | Breaking point - server overwhelmed |
+| 750+ | <10% | Complete failure |
+
+### Performance Sweet Spots
+
+1. **For Low Latency** (< 1s response time):
+   - Use ≤ 100 concurrent connections
+   - Expect ~97 req/s throughput
+   - p99 latency: 1 second
+
+2. **For Maximum Throughput**:
+   - Use 200-300 concurrent connections
+   - Achieve 130-150 req/s
+   - p99 latency: 1.2-1.9 seconds
+
+3. **For Maximum Capacity**:
+   - Use up to 600 concurrent connections
+   - Achieve ~113 req/s
+   - p99 latency: ~7 seconds
+
+### Capacity Limits
+
+- **Absolute Maximum**: 600 concurrent connections
+- **Safe Operating Limit**: 500 concurrent connections (with buffer)
+- **Recommended Production Limit**: 400 concurrent connections
+- **Breaking Point**: 650-700 concurrent connections
+
+### Comparison: Local vs Deployed
+
+| Metric | Local (2 vCPU) | HF Spaces (2 vCPU) | Notes |
+|--------|----------------|-------------------|-------|
+| Max Concurrent | 100 | 600 | HF handles 6x more! |
+| Throughput | 600 req/s | 113-150 req/s | Network overhead |
+| p50 Latency | 20ms | 500ms | Network + processing |
+| Breaking Point | 100 clients | 650 clients | Better infrastructure |
+
+---
+
+## Load Testing Guide
+
+### Prerequisites
+
+```bash
+# Install dependencies
+pip install httpx
+
+# Or using uv (recommended)
+uv pip install httpx
+```
+
+### Test Tools Overview
+
+We provide a comprehensive load testing tool (`load_test.py`) with three modes:
+
+1. **Standard Mode**: Runs predefined test suite (light, medium, heavy load)
+2. **Stress Mode**: Finds the breaking point progressively
+3. **Custom Mode**: Run specific test configurations
+
+### Testing Local Server
+
+#### 1. Start the Local Server
+
+```bash
+# Terminal 1: Start the server
+cd /path/to/mcp-server
+source .venv/bin/activate  # or use uv
+uvicorn app:app --host 0.0.0.0 --port 7860 --workers 1
+```
+
+#### 2. Run Load Tests
+
+```bash
+# Terminal 2: Run tests
+
+# Standard test suite (recommended first test)
+python load_test.py --mode standard
+
+# Custom test with specific parameters
+python load_test.py --mode custom --clients 50 --requests 20 --delay 0.05
+
+# Stress test to find breaking point
+python load_test.py --mode stress
+
+# Test with real API key
+python load_test.py --api-key YOUR_WANDB_API_KEY --mode custom --clients 10 --requests 5
+```
+
+### Testing Deployed Hugging Face Space
+
+#### 1. Basic Functionality Test
+
+```bash
+# Test with small load first
+python load_test.py \
+    --url https://mcp.withwandb.com \
+    --mode custom \
+    --clients 5 \
+    --requests 3
+```
+
+#### 2. Progressive Load Testing
+
+```bash
+# Light load (10 clients)
+python load_test.py \
+    --url https://mcp.withwandb.com \
+    --mode custom \
+    --clients 10 \
+    --requests 10
+
+# Medium load (50 clients) 
+python load_test.py \
+    --url https://mcp.withwandb.com \
+    --mode custom \
+    --clients 50 \
+    --requests 10 \
+    --delay 0.05
+
+# Heavy load (100 clients) - be careful!
+python load_test.py \
+    --url https://mcp.withwandb.com \
+    --mode custom \
+    --clients 100 \
+    --requests 20 \
+    --delay 0.01
+```
+
+#### 3. Comprehensive Stress Test
+
+```bash
+# Run full stress test (gradually increases load)
+python load_test.py \
+    --url https://mcp.withwandb.com \
+    --mode stress
+```
+
+### Creating Custom Stress Tests
+
+For finding exact breaking points, create a custom test script:
+
+```python
+#!/usr/bin/env python3
+"""Custom stress test for finding precise limits"""
+
+import asyncio
+import time
+import httpx
+
+async def test_concurrent_load(url, num_clients):
+    """Test specific number of concurrent clients"""
+    
+    async def make_request(client):
+        try:
+            response = await client.post(
+                f"{url}/mcp",
+                headers={
+                    "Authorization": "Bearer test_key_12345678901234567890",
+                    "Content-Type": "application/json",
+                    "Accept": "application/json, text/event-stream",
+                },
+                json={
+                    "jsonrpc": "2.0",
+                    "method": "initialize",
+                    "params": {
+                        "protocolVersion": "2025-06-18",
+                        "capabilities": {},
+                        "clientInfo": {"name": "stress_test", "version": "1.0"}
+                    },
+                    "id": 1
+                },
+                timeout=60
+            )
+            return response.status_code == 200
+        except:
+            return False
+    
+    print(f"Testing {num_clients} concurrent clients...")
+    start = time.time()
+    
+    async with httpx.AsyncClient(limits=httpx.Limits(max_connections=1000)) as client:
+        tasks = [make_request(client) for _ in range(num_clients)]
+        results = await asyncio.gather(*tasks)
+    
+    elapsed = time.time() - start
+    success_count = sum(results)
+    success_rate = (success_count / num_clients) * 100
+    
+    print(f"  ✅ Success: {success_count}/{num_clients} ({success_rate:.1f}%)")
+    print(f"  ⚡ Throughput: {num_clients/elapsed:.2f} req/s")
+    print(f"  ⏱️  Time: {elapsed:.2f}s")
+    
+    return success_rate
+
+async def main():
+    # Test specific range to find breaking point
+    for clients in [500, 550, 600, 650, 700]:
+        success_rate = await test_concurrent_load(
+            "https://mcp.withwandb.com", 
+            clients
+        )
+        if success_rate < 50:
+            print(f"🔥 Breaking point at {clients} clients!")
+            break
+        await asyncio.sleep(3)  # Let server recover
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Understanding Test Results
+
+#### Key Metrics to Monitor
+
+1. **Success Rate**: Percentage of successful requests
+   - 100%: Perfect performance
+   - 90-99%: Acceptable with retries
+   - <90%: Performance issues
+   - <50%: Breaking point
+
+2. **Throughput (req/s)**: Total requests per second
+   - Local: Can achieve 600+ req/s
+   - HF Spaces: Typically 100-150 req/s peak
+
+3. **Response Time Percentiles**:
+   - p50 (median): Typical response time
+   - p95: 95% of requests faster than this
+   - p99: 99% of requests faster than this
+
+4. **Resource Usage**:
+   - Monitor HF Space dashboard for CPU/Memory
+   - Local: Use `htop` or system monitor
+
+### Test Results Interpretation
+
+```
+============================================================
+Load Test Results
+============================================================
+
+📊 Overall Metrics:
+  Total Time: 3.46s              # How long the test took
+  Total Requests: 2100            # Total requests made
+  Successful: 2100 (100.0%)       # Success rate - key metric!
+  Failed: 0                       # Should be 0 for good performance
+  Requests/Second: 607.33         # Throughput
+
+🔑 Session Creation:
+  Mean: 1.348s                    # Average time to create session
+  Median: 1.342s                  # Middle value (less affected by outliers)
+  Std Dev: 0.157s                 # Consistency (lower is better)
+
+🔧 Tool Calls:
+  Mean: 0.024s                    # Average tool call time
+  Median: 0.020s                  # Typical tool call time
+  Min: 0.001s                     # Fastest response
+  Max: 0.077s                     # Slowest response
+
+📈 Latency Percentiles:
+  p50: 0.020s                     # 50% of requests faster than this
+  p95: 0.070s                     # 95% of requests faster than this  
+  p99: 0.076s                     # 99% of requests faster than this
+
+⚡ Throughput:
+  Concurrent Clients: 100         # Number of simultaneous clients
+  Requests/Second/Client: 6.07    # Per-client throughput
+  Total Throughput: 606.83 req/s  # Overall server throughput
+```
+
+---
+
+## Hardware Scaling Analysis
+
+### Current Configuration (2 vCPU, 16GB RAM on HF Spaces)
+
+**Actual Measured Performance**:
+- ✅ 600 concurrent connections with 100% success
+- ✅ 113-150 req/s sustained throughput
+- ✅ 100% reliability up to 600 clients
+- ✅ Graceful degradation 600-700 clients
+
+**This significantly exceeds initial estimates!** The combination of:
+- Efficient async architecture
+- HF Spaces infrastructure
+- Optimized connection handling
+
+Results in 6x better performance than expected.
+
+### Potential Upgrade (8 vCPU, 32GB RAM)
+
+**Estimated Performance** (linear scaling from current):
+- ~2,400 concurrent connections (4x current)
+- ~450-600 req/s throughput
+- Better response times under load
+- More consistent p99 latencies
+
+### Scaling Factors
+
+| Resource | Impact on Performance |
+|----------|---------------------|
+| **CPU Cores** | More concurrent request processing, better I/O scheduling |
+| **RAM** | Larger connection pools, more session storage, better caching |
+| **Network** | HF Spaces has excellent network infrastructure |
+| **Event Loop** | Single async loop scales well with resources |
+
+---
+
+## Optimization Strategies
+
+### 1. Connection Pooling
+```python
+# Already implemented in httpx clients
+connector = httpx.AsyncHTTPTransport(
+    limits=httpx.Limits(
+        max_connections=100,
+        max_keepalive_connections=50
+    )
+)
+```
+
+### 2. Session Management
+```python
+# Periodic cleanup of old sessions
+async def cleanup_old_sessions():
+    """Remove sessions older than 1 hour"""
+    cutoff = time.time() - 3600
+    for session_id in list(session_api_keys.keys()):
+        if session_timestamps.get(session_id, 0) < cutoff:
+            del session_api_keys[session_id]
+```
+
+### 3. Rate Limiting
+```python
+# Add per-client rate limiting
+from slowapi import Limiter
+limiter = Limiter(key_func=get_remote_address)
+
+@app.post("/mcp")
+@limiter.limit("100/minute")
+async def mcp_endpoint(request: Request):
+    # Handle request
+```
+
+### 4. Response Caching
+- Cache frequently accessed data (entity/project lists)
+- Use TTL-based caching for tool responses
+- Implement ETag support for conditional requests
+
+### 5. Monitoring & Metrics
+```python
+# Add Prometheus metrics
+from prometheus_client import Counter, Histogram, Gauge
+
+request_count = Counter('mcp_requests_total', 'Total requests', ['method', 'status'])
+request_duration = Histogram('mcp_request_duration_seconds', 'Request duration', ['method'])
+active_sessions = Gauge('mcp_active_sessions', 'Number of active sessions')
+```
+
+---
+
+## Deployment Recommendations
+
+### By Team Size
+
+#### Development/Testing (1-10 users)
+- ✅ Current HF Space perfect
+- Sub-second response times
+- No changes needed
+
+#### Small Teams (10-50 users)
+- ✅ Current HF Space excellent
+- ~86 req/s throughput
+- Response times < 600ms
+
+#### Medium Organizations (50-200 users)
+- ✅ Current HF Space adequate
+- 150 req/s peak throughput
+- Recommendations:
+  - Implement request queueing
+  - Add client-side retries
+  - Set up monitoring
+
+#### Large Deployments (200-500 users)
+- ⚠️ Current HF Space at limits
+- Recommendations:
+  - Implement load balancer
+  - Add monitoring/alerting (>400 connections)
+  - Consider upgrading HF Space tier
+  - Or deploy multiple instances
+
+#### Enterprise (500+ users)
+- ❌ Exceeds current capacity
+- Solutions:
+  - Deploy on dedicated infrastructure
+  - Use Kubernetes with HPA
+  - Implement Redis for session storage
+  - Multiple server instances with load balancing
+
+### Production Checklist
+
+If deploying for production use:
+
+1. **Monitoring Setup**:
+   ```bash
+   # Set up alerts for:
+   - Concurrent connections > 400
+   - p99 latency > 5s
+   - Success rate < 95%
+   - Memory usage > 80%
+   ```
+
+2. **Client Configuration**:
+   ```python
+   # Recommended client settings
+   client = httpx.AsyncClient(
+       timeout=httpx.Timeout(30.0),  # 30 second timeout
+       limits=httpx.Limits(
+           max_connections=10,        # Per-client connection limit
+           max_keepalive_connections=5
+       )
+   )
+   
+   # Implement exponential backoff
+   async def retry_with_backoff(func, max_retries=3):
+       for i in range(max_retries):
+           try:
+               return await func()
+           except Exception as e:
+               if i == max_retries - 1:
+                   raise
+               await asyncio.sleep(2 ** i)  # Exponential backoff
+   ```
+
+3. **Rate Limiting**:
+   - Limit per-client to 100 requests/minute
+   - Implement request quotas per API key
+   - Add circuit breakers for failing clients
+
+4. **Documentation**:
+   - Document the 500 client soft limit
+   - Provide client configuration examples
+   - Create runbooks for high load scenarios
+
+---
+
+## Future Scaling Options
+
+When the single-worker architecture reaches its limits (500+ concurrent users), here's the scaling progression:
+
+### Immediate Options (No Code Changes)
+
+1. **Vertical Scaling**: 
+   - Upgrade to 8 vCPU, 32GB RAM HF Space
+   - Expected: 2,400 concurrent connections, 450-600 req/s
+   - Cost: ~4x higher but 4-5x performance gain
+
+2. **Edge Deployment**:
+   - Deploy in multiple regions with geo-routing
+   - Reduce latency for global users
+   - Each region handles its own sessions
+
+### Advanced Options (Code Changes Required)
+
+#### Option 1: Horizontal Scaling with External Session Store
+
+Replace in-memory session storage with Redis:
+
+```python
+# Redis-based session management
+import redis.asyncio as redis
+
+class RedisSessionStore:
+    def __init__(self, redis_url: str):
+        self.redis = redis.from_url(redis_url)
+    
+    async def set_session(self, session_id: str, api_key: str):
+        await self.redis.setex(f"mcp:session:{session_id}", 3600, api_key)
+    
+    async def get_session(self, session_id: str) -> Optional[str]:
+        return await self.redis.get(f"mcp:session:{session_id}")
+```
+
+This enables multiple worker processes while maintaining session state.
+
+### Option 2: Edge Caching with CDN
+
+For read-heavy workloads:
+- Cache tool responses at CDN edge
+- Use cache keys based on (tool, params, api_key_hash)
+- TTL based on data freshness requirements
+
+### Option 3: Serverless Functions
+
+For specific tools that don't need session state:
+- Deploy stateless tools as AWS Lambda / Cloud Functions
+- Route via API Gateway
+- Scale to thousands of concurrent executions
+
+### Option 4: WebSocket Upgrade
+
+For real-time applications:
+- Upgrade to WebSocket connections
+- Maintain persistent connections
+- Push updates to clients
+- Reduce connection overhead
+
+### Option 5: Multi-Region Deployment
+
+For global distribution:
+- Deploy in multiple regions
+- Use GeoDNS for routing
+- Implement cross-region session sync
+- Reduce latency for global users
+
+---
+
+### Option 6: Platform-Specific Solutions
+
+When platforms evolve to better support stateful applications:
+
+1. **Kubernetes StatefulSets**: 
+   - When HF Spaces supports Kubernetes
+   - Maintains pod identity across restarts
+   - Enables persistent volume claims
+
+2. **Durable Objects** (Cloudflare Workers):
+   - Edge computing with guaranteed session affinity
+   - Automatic scaling with state persistence
+   - Global distribution
+
+---
+
+## Common Questions About the Architecture
+
+### Q: Why not use multiple workers like traditional web apps?
+
+**A**: MCP is a stateful protocol, similar to WebSockets or GraphQL subscriptions. Multiple workers would break session continuity unless you add complex state synchronization (Redis, sticky sessions), which adds latency and complexity without improving performance for our I/O-bound workload.
+
+### Q: Is single-worker a bottleneck?
+
+**A**: No. Our tests show a single async worker handles **600+ concurrent connections** and **150 req/s** on just 2 vCPUs. The bottleneck is network I/O to W&B APIs, not CPU processing. Adding workers wouldn't improve this.
+
+### Q: How does this compare to multi-threaded servers?
+
+**A**: Python's GIL (Global Interpreter Lock) makes true multi-threading inefficient for CPU-bound work. For I/O-bound work (like our API calls), async/await with a single thread is actually more efficient than multi-threading due to lower overhead and no context switching.
+
+### Q: What about reliability and fault tolerance?
+
+**A**: 
+- **Health checks**: HF Spaces automatically restarts unhealthy containers
+- **Graceful shutdown**: Server properly closes connections on restart
+- **Session recovery**: Clients can re-authenticate with Bearer token
+- **Error handling**: Each request is isolated; one failure doesn't affect others
+
+### Q: When would you need to change this architecture?
+
+**A**: Only when:
+1. CPU-bound processing becomes significant (unlikely for MCP proxy)
+2. You need 1000+ concurrent users (then use Redis for sessions)
+3. Global distribution is required (deploy regional instances)
+
+---
+
+## Summary
+
+The W&B MCP Server on Hugging Face Spaces **significantly exceeds expectations**, handling 6x more concurrent connections than initially estimated. 
+
+**Architecture Highlights**:
+- 🏗️ **Single-worker async**: The correct choice for stateful protocols
+- 🚀 **600 concurrent connections**: Proven capacity with 100% success rate
+- ⚡ **150 req/s peak throughput**: Excellent for I/O-bound operations
+- 🎯 **Simple and reliable**: No complex state synchronization needed
+
+**Key Achievements**:
+- ✅ **Industry-standard architecture** for stateful protocols
+- ✅ **Production-ready** for teams up to 500 users
+- ✅ **Clear scaling path** for larger deployments
+- ✅ **Cost-effective** on basic HF Space tier
+
+**Bottom Line by Team Size**:
+- ✅ **Development** (1-10 users): Perfect
+- ✅ **Small Teams** (10-50 users): Excellent  
+- ✅ **Medium Teams** (50-200 users): Good
+- ⚠️ **Large Teams** (200-500 users): Adequate with monitoring
+- ❌ **Enterprise** (500+ users): Needs infrastructure upgrade
+
+The single-worker async architecture is not a limitation but a **deliberate design choice** that aligns with MCP's requirements and industry best practices for stateful protocols. The deployment on Hugging Face Spaces provides excellent value and surprising performance for small to medium-scale deployments.

app.py

@@ -148,10 +148,14 @@ async def thread_safe_auth_middleware(request: Request, call_next):
         
         # Check if request has MCP session ID (for established sessions)
         session_id = request.headers.get("Mcp-Session-Id")
-        if session_id and session_id in session_api_keys:
-            # Use stored API key for this session
-            api_key = session_api_keys[session_id]
-            logger.debug(f"Using stored API key for session {session_id[:8]}...")
+        if session_id:
+            logger.debug(f"MCP Session ID present: {session_id[:8]}...")
+            if session_id in session_api_keys:
+                # Use stored API key for this session
+                api_key = session_api_keys[session_id]
+                logger.debug(f"Using stored API key for session {session_id[:8]}...")
+            else:
+                logger.debug(f"Session ID not found in storage. Active sessions: {len(session_api_keys)}")
         
         # Check for Bearer token (for new sessions or explicit auth)
         authorization = request.headers.get("Authorization", "")
@@ -189,7 +193,10 @@ async def thread_safe_auth_middleware(request: Request, call_next):
                 session_id = response.headers.get("Mcp-Session-Id")
                 if session_id and api_key:
                     session_api_keys[session_id] = api_key
-                    logger.debug(f"Stored API key for session {session_id[:8]}...")
+                    logger.info(f"New MCP session created: {session_id[:8]}... (Total sessions: {len(session_api_keys)})")
+                    logger.debug(f"   Stored API key ending in ...{api_key[-4:]}")
+                elif session_id and not api_key:
+                    logger.warning(f"Session created but no API key to store: {session_id[:8]}...")
                 
                 return response
             finally:
@@ -232,6 +239,44 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+# Add request logging middleware for debugging
+@app.middleware("http")
+async def logging_middleware(request, call_next):
+    """Log all incoming requests for debugging."""
+    import time
+    start_time = time.time()
+    
+    # Log request details
+    logger.info(f"Incoming request: {request.method} {request.url.path}")
+    logger.debug(f"   Headers: {dict(request.headers)}")
+    logger.debug(f"   Query params: {dict(request.query_params)}")
+    
+    # Track if this is an MCP endpoint
+    is_mcp = request.url.path.startswith("/mcp") or request.url.path == "/"
+    
+    try:
+        response = await call_next(request)
+        
+        # Calculate response time
+        process_time = time.time() - start_time
+        
+        # Log response details
+        status_label = "SUCCESS" if response.status_code < 400 else "ERROR" if response.status_code >= 400 else "WARNING"
+        logger.info(f"[{status_label}] Response: {request.method} {request.url.path} -> {response.status_code} ({process_time:.3f}s)")
+        
+        # Log detailed info for 404s
+        if response.status_code == 404:
+            logger.warning(f"404 Not Found for {request.url.path}")
+            logger.debug(f"   Full URL: {request.url}")
+            logger.debug(f"   Available routes: /, /health, /favicon.ico, /favicon.png, /mcp")
+            if is_mcp:
+                logger.debug("   This appears to be an MCP endpoint that wasn't handled")
+        
+        return response
+    except Exception as e:
+        logger.error(f"Error processing {request.method} {request.url.path}: {e}")
+        raise
+
 # Add authentication middleware
 @app.middleware("http")
 async def auth_middleware(request, call_next):
@@ -295,8 +340,38 @@ async def health():
     }
 
 # Mount the MCP streamable HTTP app
+# NOTE: MCP app is mounted at root "/" to handle all MCP protocol requests
+# This means it will catch all unhandled routes, which is why we define our
+# custom routes (/, /health, etc.) BEFORE mounting the MCP app
 mcp_app = mcp.streamable_http_app()
-logger.info("Mounting MCP streamable HTTP app")
+logger.info("Mounting MCP streamable HTTP app at root /")
+logger.info("Note: MCP will handle all unmatched routes, returning 404 for non-MCP requests")
+
+# For debugging: Log incoming requests to understand routing
+@app.middleware("http")
+async def mcp_routing_debug(request, call_next):
+    """Debug middleware to understand MCP routing issues."""
+    path = request.url.path
+    method = request.method
+    
+    # Check if this should be an MCP request
+    is_mcp_request = (
+        request.headers.get("Content-Type") == "application/json" and
+        (request.headers.get("Accept", "").find("text/event-stream") >= 0 or
+         request.headers.get("Accept", "").find("application/json") >= 0)
+    )
+    
+    if path == "/" and method == "GET":
+        logger.debug("Root GET request - should show landing page")
+    elif path == "/health" and method == "GET":
+        logger.debug("Health check request")
+    elif path in ["/", "/mcp"] and is_mcp_request:
+        logger.debug(f"MCP protocol request detected on {path}")
+    elif path == "/" and method in ["POST", "GET"] and not is_mcp_request:
+        logger.debug(f"Non-MCP {method} request to root - may get 404 from MCP app")
+    
+    return await call_next(request)
+
 app.mount("/", mcp_app)
 
 # Port for HF Spaces
@@ -309,10 +384,6 @@ if __name__ == "__main__":
     logger.info("Health check: /health")
     logger.info("MCP endpoint: /mcp")
     
-    # Check if we should use multiple workers
-    workers = int(os.environ.get("WEB_CONCURRENCY", "1"))
-    if workers > 1:
-        logger.info(f"Note: To run with {workers} workers, use:")
-        logger.info(f"gunicorn app_concurrent:app --bind 0.0.0.0:{PORT} --workers {workers} --worker-class uvicorn.workers.UvicornWorker")
-    
+    # Run with single async worker for MCP session compatibility
+    logger.info("Starting server with single async worker (MCP requires stateful sessions)")
     uvicorn.run(app, host="0.0.0.0", port=PORT)

gemini-extension.json

@@ -1,20 +1,14 @@
 {
-    "name": "wandb-weave",
+    "name": "wandb-mcp-server",
     "version": "0.1.0",
     "mcpServers": {
-        "wandb-weave": {
-            "command": "uv",
-            "args": [
-                "run", 
-                "--directory",
-                "/Users/niware_wb/Documents/code_projects/mcp_experiments/wandb-mcp-server",
-                "wandb_mcp_server",
-                "--transport",
-                "stdio"
-            ],
-            "env": {
-                "WANDB_API_KEY": "<your-api-key>"
-            }
+      "wandb": {
+        "httpUrl": "https://mcp.withwandb.com/mcp",
+        "trust": true,
+        "headers": {
+            "Authorization": "Bearer $WANDB_API_KEY",
+            "Accept": "application/json, text/event-stream"
         }
+      }
     }
-}
+  }

load_test.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""
+Load testing script for W&B MCP Server
+Measures concurrent connections, requests/second, and latency
+"""
+
+import asyncio
+import time
+import statistics
+from typing import List, Dict, Any, Optional
+import httpx
+import json
+from datetime import datetime
+import argparse
+import sys
+
+class MCPLoadTester:
+    def __init__(self, base_url: str = "http://localhost:7860", api_key: str = None):
+        self.base_url = base_url
+        self.api_key = api_key or "test_key_12345678901234567890123456789012345678"
+        self.metrics = {
+            "total_requests": 0,
+            "successful_requests": 0,
+            "failed_requests": 0,
+            "response_times": [],
+            "session_creation_times": [],
+            "tool_call_times": []
+        }
+    
+    async def create_session(self, client: httpx.AsyncClient) -> Optional[str]:
+        """Initialize an MCP session."""
+        start_time = time.time()
+        
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        
+        payload = {
+            "jsonrpc": "2.0",
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2025-06-18",
+                "capabilities": {},
+                "clientInfo": {"name": "load_test", "version": "1.0.0"}
+            },
+            "id": 1
+        }
+        
+        try:
+            response = await client.post(
+                f"{self.base_url}/mcp",
+                headers=headers,
+                json=payload,
+                timeout=10
+            )
+            
+            elapsed = time.time() - start_time
+            self.metrics["session_creation_times"].append(elapsed)
+            self.metrics["total_requests"] += 1
+            
+            if response.status_code == 200:
+                self.metrics["successful_requests"] += 1
+                return response.headers.get("mcp-session-id")
+            else:
+                self.metrics["failed_requests"] += 1
+                return None
+                
+        except Exception as e:
+            self.metrics["failed_requests"] += 1
+            self.metrics["total_requests"] += 1
+            print(f"Session creation failed: {e}")
+            return None
+    
+    async def call_tool(self, client: httpx.AsyncClient, session_id: str, tool_name: str, params: Dict[str, Any]):
+        """Call a tool using the session."""
+        start_time = time.time()
+        
+        headers = {
+            "Mcp-Session-Id": session_id,
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        
+        payload = {
+            "jsonrpc": "2.0",
+            "method": "tools/call",
+            "params": {
+                "name": tool_name,
+                "arguments": params
+            },
+            "id": 2
+        }
+        
+        try:
+            response = await client.post(
+                f"{self.base_url}/mcp",
+                headers=headers,
+                json=payload,
+                timeout=30
+            )
+            
+            elapsed = time.time() - start_time
+            self.metrics["tool_call_times"].append(elapsed)
+            self.metrics["response_times"].append(elapsed)
+            self.metrics["total_requests"] += 1
+            
+            if response.status_code == 200:
+                self.metrics["successful_requests"] += 1
+            else:
+                self.metrics["failed_requests"] += 1
+                
+        except Exception as e:
+            self.metrics["failed_requests"] += 1
+            self.metrics["total_requests"] += 1
+            print(f"Tool call failed: {e}")
+    
+    async def run_client_session(self, client_id: int, num_requests: int, delay: float = 0.1):
+        """Simulate a client making multiple requests."""
+        async with httpx.AsyncClient() as client:
+            # Create session
+            session_id = await self.create_session(client)
+            if not session_id:
+                return
+            
+            # Make multiple tool calls
+            for i in range(num_requests):
+                await self.call_tool(
+                    client,
+                    session_id,
+                    "query_wandb_entity_projects",  # Simple tool that doesn't need entity/project
+                    {}
+                )
+                
+                # Small delay between requests
+                if delay > 0:
+                    await asyncio.sleep(delay)
+    
+    async def run_load_test(self, num_clients: int, requests_per_client: int, delay: float = 0.1):
+        """Run the load test with specified parameters."""
+        print(f"\n{'='*60}")
+        print(f"Starting Load Test")
+        print(f"{'='*60}")
+        print(f"Clients: {num_clients}")
+        print(f"Requests per client: {requests_per_client}")
+        print(f"Total requests: {num_clients * (requests_per_client + 1)}")  # +1 for session creation
+        print(f"Server: {self.base_url}")
+        print(f"Delay between requests: {delay}s")
+        print(f"{'='*60}\n")
+        
+        # Reset metrics
+        self.metrics = {
+            "total_requests": 0,
+            "successful_requests": 0,
+            "failed_requests": 0,
+            "response_times": [],
+            "session_creation_times": [],
+            "tool_call_times": []
+        }
+        
+        start_time = time.time()
+        
+        # Run all client sessions concurrently
+        tasks = [
+            self.run_client_session(i, requests_per_client, delay)
+            for i in range(num_clients)
+        ]
+        
+        # Show progress
+        print("Running load test...")
+        await asyncio.gather(*tasks)
+        
+        total_time = time.time() - start_time
+        
+        # Calculate and display results
+        self.display_results(total_time, num_clients, requests_per_client)
+        
+        return self.metrics
+    
+    def display_results(self, total_time: float, num_clients: int, requests_per_client: int):
+        """Display load test results."""
+        print(f"\n{'='*60}")
+        print(f"Load Test Results")
+        print(f"{'='*60}")
+        
+        # Overall metrics
+        total_requests = self.metrics["total_requests"]
+        success_rate = (self.metrics["successful_requests"] / total_requests * 100) if total_requests > 0 else 0
+        
+        print(f"\n📊 Overall Metrics:")
+        print(f"  Total Time: {total_time:.2f}s")
+        print(f"  Total Requests: {total_requests}")
+        print(f"  Successful: {self.metrics['successful_requests']} ({success_rate:.1f}%)")
+        print(f"  Failed: {self.metrics['failed_requests']}")
+        if total_time > 0:
+            print(f"  Requests/Second: {total_requests / total_time:.2f}")
+        
+        # Session creation metrics
+        if self.metrics["session_creation_times"]:
+            print(f"\n🔑 Session Creation:")
+            print(f"  Mean: {statistics.mean(self.metrics['session_creation_times']):.3f}s")
+            print(f"  Median: {statistics.median(self.metrics['session_creation_times']):.3f}s")
+            if len(self.metrics["session_creation_times"]) > 1:
+                print(f"  Std Dev: {statistics.stdev(self.metrics['session_creation_times']):.3f}s")
+        
+        # Tool call metrics
+        if self.metrics["tool_call_times"]:
+            print(f"\n🔧 Tool Calls:")
+            print(f"  Mean: {statistics.mean(self.metrics['tool_call_times']):.3f}s")
+            print(f"  Median: {statistics.median(self.metrics['tool_call_times']):.3f}s")
+            if len(self.metrics["tool_call_times"]) > 1:
+                print(f"  Std Dev: {statistics.stdev(self.metrics['tool_call_times']):.3f}s")
+                print(f"  Min: {min(self.metrics['tool_call_times']):.3f}s")
+                print(f"  Max: {max(self.metrics['tool_call_times']):.3f}s")
+                
+                # Calculate percentiles
+                sorted_times = sorted(self.metrics["tool_call_times"])
+                p50_idx = len(sorted_times) // 2
+                p95_idx = min(int(len(sorted_times) * 0.95), len(sorted_times) - 1)
+                p99_idx = min(int(len(sorted_times) * 0.99), len(sorted_times) - 1)
+                
+                p50 = sorted_times[p50_idx]
+                p95 = sorted_times[p95_idx]
+                p99 = sorted_times[p99_idx]
+                
+                print(f"\n📈 Latency Percentiles:")
+                print(f"  p50: {p50:.3f}s")
+                print(f"  p95: {p95:.3f}s")
+                print(f"  p99: {p99:.3f}s")
+        
+        # Throughput
+        print(f"\n⚡ Throughput:")
+        print(f"  Concurrent Clients: {num_clients}")
+        if total_time > 0:
+            print(f"  Requests/Second/Client: {(requests_per_client + 1) / total_time:.2f}")
+            print(f"  Total Throughput: {total_requests / total_time:.2f} req/s")
+        
+        print(f"\n{'='*60}\n")
+
+
+async def run_standard_tests(base_url: str = "http://localhost:7860", api_key: str = None):
+    """Run standard load test scenarios."""
+    tester = MCPLoadTester(base_url, api_key)
+    
+    # Test 1: Light load (10 clients, 5 requests each)
+    print("\n🟢 TEST 1: Light Load")
+    await tester.run_load_test(10, 5, delay=0.1)
+    
+    # Test 2: Medium load (50 clients, 10 requests each)
+    print("\n🟡 TEST 2: Medium Load")
+    await tester.run_load_test(50, 10, delay=0.05)
+    
+    # Test 3: Heavy load (100 clients, 20 requests each)
+    print("\n🔴 TEST 3: Heavy Load")
+    await tester.run_load_test(100, 20, delay=0.01)
+
+
+async def run_stress_test(base_url: str = "http://localhost:7860", api_key: str = None):
+    """Run stress test to find breaking point."""
+    tester = MCPLoadTester(base_url, api_key)
+    
+    print("\n🔥 STRESS TEST: Finding Breaking Point")
+    print("=" * 60)
+    
+    client_counts = [10, 25, 50, 100, 200, 500]
+    results = []
+    
+    for clients in client_counts:
+        print(f"\nTesting with {clients} concurrent clients...")
+        metrics = await tester.run_load_test(clients, 10, delay=0.01)
+        
+        success_rate = (metrics["successful_requests"] / metrics["total_requests"] * 100) if metrics["total_requests"] > 0 else 0
+        results.append((clients, success_rate))
+        
+        # Stop if success rate drops below 95%
+        if success_rate < 95:
+            print(f"\n⚠️ Performance degradation detected at {clients} clients")
+            print(f"Success rate dropped to {success_rate:.1f}%")
+            break
+    
+    print("\n📊 Stress Test Summary:")
+    print("Clients | Success Rate")
+    print("--------|-------------")
+    for clients, rate in results:
+        print(f"{clients:7d} | {rate:6.1f}%")
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Load test W&B MCP Server')
+    parser.add_argument('--url', default='http://localhost:7860', help='Server URL')
+    parser.add_argument('--api-key', help='W&B API key (optional, uses test key if not provided)')
+    parser.add_argument('--mode', choices=['standard', 'stress', 'custom'], default='standard',
+                        help='Test mode: standard, stress, or custom')
+    parser.add_argument('--clients', type=int, default=10, help='Number of concurrent clients (for custom mode)')
+    parser.add_argument('--requests', type=int, default=10, help='Requests per client (for custom mode)')
+    parser.add_argument('--delay', type=float, default=0.1, help='Delay between requests in seconds (for custom mode)')
+    
+    args = parser.parse_args()
+    
+    print("W&B MCP Server Load Tester")
+    print(f"Server: {args.url}")
+    print(f"Mode: {args.mode}")
+    
+    if args.mode == 'standard':
+        asyncio.run(run_standard_tests(args.url, args.api_key))
+    elif args.mode == 'stress':
+        asyncio.run(run_stress_test(args.url, args.api_key))
+    else:  # custom
+        tester = MCPLoadTester(args.url, args.api_key)
+        asyncio.run(tester.run_load_test(args.clients, args.requests, args.delay))
+
+
+if __name__ == "__main__":
+    main()