feat(authentication): Disable the OAuth flow when running on HTTP mode

Author: timothedelion

DEVELOPMENT.md

@@ -135,18 +135,55 @@ for tool in example_tools:
     mcp.tool(tool)
 ```
 
+## Authentication Modes
+
+The GitGuardian MCP server supports two authentication modes:
+
+### 1. Local OAuth (stdio transport)
+For desktop applications using stdio transport, OAuth authentication is available:
+
+```bash
+ENABLE_LOCAL_OAUTH=true developer-mcp-server
+```
+
+This will:
+- Open a browser for OAuth authentication
+- Store the token locally in `~/.gitguardian/`
+- Reuse the token across sessions
+
+### 2. Per-Request Authentication (HTTP/SSE transport)
+For server deployments using HTTP/SSE transport, use per-request PAT authentication:
+
+```bash
+MCP_PORT=8080 MCP_HOST=127.0.0.1 developer-mcp-server
+```
+
+Clients must provide authentication via the Authorization header:
+```
+Authorization: Bearer <your-personal-access-token>
+```
+
+**Important:** You cannot use both modes simultaneously. The server will raise an error if both `MCP_PORT` and `ENABLE_LOCAL_OAUTH=true` are set.
+
+### 3. Environment Variable PAT
+For all transport modes, you can provide a PAT via environment variable:
+
+```bash
+GITGUARDIAN_PERSONAL_ACCESS_TOKEN=<your-pat> developer-mcp-server
+```
+
 ## Testing
 
-Run tests using uv:
+Run tests using uv (OAuth is disabled by default in tests):
 
 ```bash
-uv run pytest
+ENABLE_LOCAL_OAUTH=false uv run pytest
 ```
 
 Run tests with verbose output:
 
 ```bash
-uv run pytest -v
+ENABLE_LOCAL_OAUTH=false uv run pytest -v
 ```
 
 Run tests with coverage:

README.md

@@ -175,12 +175,103 @@ To use the GitGuardian MCP server with [Windsurf](https://www.windsurf.ai/):
    }
    ```
 
-## Authentication Process
+## Authentication
 
-1. When you start the server, it will automatically open a browser window to authenticate with GitGuardian
-2. After you log in to GitGuardian and authorize the application, you'll be redirected back to the local server
-3. The authentication token will be securely stored for future use
-4. The next time you start the server, it will reuse the stored token without requiring re-authentication
+The GitGuardian MCP server supports multiple authentication methods depending on your deployment mode.
+
+### OAuth Authentication (Default for stdio transport)
+
+When using stdio transport (the default for desktop IDE integrations), the server uses OAuth for authentication by default:
+
+1. OAuth is **enabled by default** (`ENABLE_LOCAL_OAUTH=true`) for local-first usage
+2. When you start the server, it will automatically open a browser window to authenticate with GitGuardian
+3. After you log in to GitGuardian and authorize the application, you'll be redirected back to the local server
+4. The authentication token will be securely stored in `~/.gitguardian/` for future use
+5. The next time you start the server, it will reuse the stored token without requiring re-authentication
+
+**Example configuration (OAuth is enabled by default, no need to specify):**
+
+```json
+{
+  "mcpServers": {
+    "GitGuardianDeveloper": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/GitGuardian/ggmcp.git",
+        "developer-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+**To disable OAuth** (e.g., for using PAT instead):
+
+```json
+{
+  "mcpServers": {
+    "GitGuardianDeveloper": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/GitGuardian/ggmcp.git",
+        "developer-mcp-server"
+      ],
+      "env": {
+        "ENABLE_LOCAL_OAUTH": "false",
+        "GITGUARDIAN_PERSONAL_ACCESS_TOKEN": "your_pat_here"
+      }
+    }
+  }
+}
+```
+
+### Personal Access Token (PAT) Authentication
+
+For non-interactive environments, CI/CD pipelines, or when you prefer not to use OAuth, you can authenticate using a Personal Access Token:
+
+1. Create a Personal Access Token in your GitGuardian dashboard
+2. Set the `GITGUARDIAN_PERSONAL_ACCESS_TOKEN` environment variable
+
+**Example configuration with PAT:**
+
+```json
+{
+  "mcpServers": {
+    "GitGuardianDeveloper": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/GitGuardian/ggmcp.git",
+        "developer-mcp-server"
+      ],
+      "env": {
+        "GITGUARDIAN_PERSONAL_ACCESS_TOKEN": "your_personal_access_token_here"
+      }
+    }
+  }
+}
+```
+
+### Per-Request Authentication (HTTP/SSE transport)
+
+When using HTTP/SSE transport (with `MCP_PORT` set), the server expects authentication via the `Authorization` header in each HTTP request. This is the recommended approach for server deployments.
+
+**Important:** Since `ENABLE_LOCAL_OAUTH` defaults to `true`, you **must explicitly set it to `false`** when using HTTP/SSE mode:
+
+```bash
+# Start server with HTTP transport (OAuth must be disabled)
+ENABLE_LOCAL_OAUTH=false MCP_PORT=8000 MCP_HOST=127.0.0.1 uvx --from git+https://github.com/GitGuardian/ggmcp.git developer-mcp-server
+
+# Make authenticated request
+curl -X POST http://127.0.0.1:8000/tools/list \
+  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+**Configuration validation:** The server will raise an error if both `MCP_PORT` and `ENABLE_LOCAL_OAUTH=true` are set, as HTTP/SSE mode requires per-request authentication for security reasons.
 
 ## Configuration for Different GitGuardian Instances
 
@@ -197,7 +288,9 @@ The following environment variables can be configured:
 | `GITGUARDIAN_SCOPES` | OAuth scopes to request | Auto-detected based on instance type | `scan,incidents:read,sources:read,honeytokens:read,honeytokens:write` |
 | `GITGUARDIAN_TOKEN_NAME` | Name for the OAuth token | Auto-generated based on server type | `"Developer MCP Token"` |
 | `GITGUARDIAN_TOKEN_LIFETIME` | Token lifetime in days | `30` | `60` or `never` |
-| `MCP_PORT` | Port for HTTP/SSE transport (when set, enables HTTP transport instead of stdio) | Not set (uses stdio) | `8000` |
+| `GITGUARDIAN_PERSONAL_ACCESS_TOKEN` | Personal Access Token for authentication (alternative to OAuth) | Not set | `YOUR_PAT_TOKEN` |
+| `ENABLE_LOCAL_OAUTH` | Enable local OAuth flow (stdio mode only, cannot be used with `MCP_PORT`) | `true` (enabled by default for local-first usage) | `false` |
+| `MCP_PORT` | Port for HTTP/SSE transport (when set, enables HTTP transport instead of stdio, requires `ENABLE_LOCAL_OAUTH=false`) | Not set (uses stdio) | `8000` |
 | `MCP_HOST` | Host address for HTTP/SSE transport | `127.0.0.1` | `0.0.0.0` |
 
 ### HTTP/SSE Transport
@@ -206,7 +299,7 @@ By default, the MCP server uses **stdio transport** for local IDE integrations.
 
 #### Enabling HTTP Transport
 
-To enable HTTP/SSE transport, set the `MCP_PORT` environment variable:
+To enable HTTP/SSE transport, set the `MCP_PORT` environment variable. **Important:** You must also set `ENABLE_LOCAL_OAUTH=false` since OAuth defaults to enabled:
 
 ```json
 {
@@ -219,6 +312,7 @@ To enable HTTP/SSE transport, set the `MCP_PORT` environment variable:
         "developer-mcp-server"
       ],
       "env": {
+        "ENABLE_LOCAL_OAUTH": "false",
         "MCP_PORT": "8000",
         "MCP_HOST": "127.0.0.1"
       }
@@ -232,15 +326,15 @@ To enable HTTP/SSE transport, set the `MCP_PORT` environment variable:
 You can also run the server directly with HTTP transport:
 
 ```bash
-# Run with HTTP transport
-MCP_PORT=8000 MCP_HOST=127.0.0.1 uvx --from git+https://github.com/GitGuardian/ggmcp.git developer-mcp-server
+# Run with HTTP transport (must disable OAuth)
+ENABLE_LOCAL_OAUTH=false MCP_PORT=8000 MCP_HOST=127.0.0.1 uvx --from git+https://github.com/GitGuardian/ggmcp.git developer-mcp-server
 ```
 
 The server will automatically start on `http://127.0.0.1:8000` and be accessible for remote integrations.
 
 #### Authentication via Authorization Header
 
-When using HTTP/SSE transport, you can authenticate using a Personal Access Token (PAT) via the `Authorization` header. This is useful for remote integrations where environment variables or OAuth flows are not practical.
+When using HTTP/SSE transport, authentication is done via the `Authorization` header on each request. See the [Per-Request Authentication](#per-request-authentication-httpsse-transport) section for detailed configuration.
 
 **Supported header formats:**
 - `Authorization: Bearer <token>`
@@ -285,11 +379,10 @@ async with httpx.AsyncClient() as client:
 **Authentication Priority:**
 
 When using HTTP transport, the authentication priority is:
-1. **Authorization header** (if present in the HTTP request)
-2. **GITGUARDIAN_PERSONAL_ACCESS_TOKEN** environment variable
-3. **OAuth flow** (default fallback)
+1. **Authorization header** (if present in the HTTP request) - recommended for HTTP/SSE mode
+2. **GITGUARDIAN_PERSONAL_ACCESS_TOKEN** environment variable - fallback option
 
-This allows different clients to use different authentication methods when connecting to the same HTTP server instance.
+Note that OAuth (`ENABLE_LOCAL_OAUTH=true`) is not supported in HTTP/SSE mode for security reasons. Each HTTP request must include its own authentication credentials.
 
 **Notes:**
 - `uvicorn` is included as a dependency - no additional installation needed.
@@ -388,17 +481,19 @@ This project includes a comprehensive test suite to ensure functionality and pre
 
 2. Run the test suite:
    ```bash
-   uv run pytest
+   ENABLE_LOCAL_OAUTH=false uv run pytest
    ```
 
+   Note: Tests disable OAuth by default via the `ENABLE_LOCAL_OAUTH=false` environment variable to prevent OAuth prompts during test execution.
+
 3. Run tests with verbose output:
    ```bash
-   uv run pytest -v
+   ENABLE_LOCAL_OAUTH=false uv run pytest -v
    ```
 
 4. Run tests with coverage:
    ```bash
-   uv run pytest --cov=packages --cov-report=html
+   ENABLE_LOCAL_OAUTH=false uv run pytest --cov=packages --cov-report=html
    ```
 
 This will run all tests and generate a coverage report showing which parts of the codebase are covered by tests.

packages/developer_mcp_server/src/developer_mcp_server/server.py

@@ -3,7 +3,7 @@
 import logging
 import os
 
-from gg_api_core.mcp_server import GitGuardianFastMCP
+from gg_api_core.mcp_server import get_mcp_server
 from gg_api_core.scopes import set_developer_scopes
 
 from developer_mcp_server.register_tools import DEVELOPER_INSTRUCTIONS, register_developer_tools
@@ -14,7 +14,7 @@
 logger = logging.getLogger(__name__)
 
 # Use our custom GitGuardianFastMCP from the core package
-mcp = GitGuardianFastMCP(
+mcp = get_mcp_server(
     "GitGuardian Developer",
     log_level="DEBUG",
     instructions=DEVELOPER_INSTRUCTIONS,

packages/gg_api_core/README.md

@@ -23,7 +23,8 @@ from gg_api_core.mcp_server import GitGuardianFastMCP
 from gg_api_core.client import GitGuardianClient
 
 # Create a custom MCP server
-mcp = GitGuardianFastMCP("My Custom Server")
+mcp = get_mcp_server("My Custom Server")
+
 
 # Register tools that use the GitGuardian API
 @mcp.tool(required_scopes=["honeytokens:read"])

packages/gg_api_core/src/gg_api_core/client.py

@@ -67,6 +67,20 @@ class TagNames(str, Enum):
     REVOCABLE_BY_GG = "REVOCABLE_BY_GG"
 
 
+def is_oauth_enabled() -> bool:
+    """
+    Check if OAuth authentication is enabled via environment variable.
+    """
+    if os.environ.get("ENABLE_LOCAL_OAUTH") is None:
+        # Default value is True
+        return True
+    return os.environ.get("ENABLE_LOCAL_OAUTH", "").lower() == "true"
+
+
+def get_personal_access_token_from_env() -> str | None:
+    return os.environ.get("GITGUARDIAN_PERSONAL_ACCESS_TOKEN")
+
+
 class GitGuardianClient:
     """Client for interacting with the GitGuardian API."""
 
@@ -105,16 +119,33 @@ def _init_urls(self, gitguardian_url: str | None = None):
         logger.info(f"Using private API URL: {self.private_api_url}")
 
     def _init_personal_access_token(self, personal_access_token: str | None = None):
+        # Validate OAuth configuration
+        mcp_port = os.environ.get("MCP_PORT")
+        enable_local_oauth = is_oauth_enabled()
+
         if personal_access_token:
             logger.info("Using provided PAT")
             self._oauth_token = personal_access_token
-        elif personal_access_token := os.environ.get("GITGUARDIAN_PERSONAL_ACCESS_TOKEN"):
-            logger.info("Using PAT from environment variable")
-            self._oauth_token = personal_access_token
+            return
+
+        if mcp_port:
+            if enable_local_oauth:
+                raise ValueError(
+                    "Invalid configuration: Cannot use ENABLE_LOCAL_OAUTH=true with MCP_PORT set. "
+                    "HTTP/SSE mode requires per-request authentication via Authorization headers. "
+                    "For local OAuth authentication, use stdio transport (unset MCP_PORT)."
+                )
         else:
-            # TODO(APPAI): We should also locate here the retrieval from storage
-            logger.info("No PAT provided, falling back to OAuth")
-            self._oauth_token = None
+            if personal_access_token:
+                logger.info("Using provided PAT")
+                self._oauth_token = personal_access_token
+            elif personal_access_token := os.environ.get("GITGUARDIAN_PERSONAL_ACCESS_TOKEN"):
+                logger.info("Using PAT from environment variable")
+                self._oauth_token = personal_access_token
+            else:
+                # TODO(APPAI): We should also locate here the retrieval from storage
+                logger.info("No PAT provided, falling back to OAuth")
+                self._oauth_token = None
 
     def _normalize_api_url(self, api_url: str) -> str:
         """
@@ -221,12 +252,20 @@ def _get_dashboard_url(self) -> str:
             logger.warning(f"Failed to extract dashboard URL from API URL: {e}")
             return default_dashboard_url
 
-    async def _ensure_oauth_token(self):
-        """Ensure we have a valid OAuth token, initiating the OAuth flow if needed."""
+    async def _ensure_api_token(self):
+        """Ensure we have a valid token, initiating the OAuth flow if needed.
+
+        OAuth flow is only enabled when ENABLE_LOCAL_OAUTH=true.
+        This prevents OAuth prompts in HTTP/SSE mode (which uses per-request PATs)
+        and in test environments.
+        """
 
         if self._oauth_token is not None:
             return
 
+        if not is_oauth_enabled():
+            raise RuntimeError("OAuth is not enabled")
+
         # Use a global lock to prevent parallel OAuth flows across all client instances
         async with _oauth_lock:
             # Double-check pattern: another thread might have completed OAuth while we waited for the lock
@@ -322,7 +361,7 @@ async def _clear_invalid_oauth_token(self):
             logger.warning(f"Could not clean up token storage: {str(e)}")
 
         # Force new OAuth flow on next request
-        await self._ensure_oauth_token()
+        await self._ensure_api_token()
 
     async def _request(
         self, method: str, endpoint: str, return_headers: bool = False, **kwargs
@@ -359,7 +398,7 @@ async def _request(
             logger.debug(f"Request body: {safe_json}")
 
         # Ensure we have a valid OAuth token
-        await self._ensure_oauth_token()
+        await self._ensure_api_token()
         headers = {
             "Authorization": f"Token {self._oauth_token}",
             "Content-Type": "application/json",