fix(mcp): resolve 307 redirect issue by enforcing trailing slash in URLs

- Updated MCP documentation to include trailing slash in all URL examples
- Modified frontend MCP page to reflect the correct endpoint with trailing slash
- Adjusted FastAPI middleware to handle requests to /mcp without redirecting

Author: MarkusNeusinger

api/main.py

@@ -148,6 +148,29 @@ async def add_cache_headers(request: Request, call_next):
 app.include_router(debug_router)
 
 
+# ASGI middleware to handle /mcp without trailing slash
+# This runs BEFORE FastAPI routing, avoiding the 307 redirect
+# MCP clients like Claude CLI don't follow redirects
+class MCPTrailingSlashMiddleware:
+    """Rewrite /mcp to /mcp/ before routing to avoid 307 redirect."""
+
+    def __init__(self, asgi_app):
+        self.asgi_app = asgi_app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http" and scope["path"] == "/mcp":
+            scope = scope.copy()
+            scope["path"] = "/mcp/"
+        await self.asgi_app(scope, receive, send)
+
+
+# Wrap the FastAPI app with the middleware
+# This must be done after all routers are registered
+# Keep reference to FastAPI instance for tests
+fastapi_app = app
+app = MCPTrailingSlashMiddleware(app)
+
+
 if __name__ == "__main__":
     import uvicorn
 

api/routers/seo.py

@@ -71,6 +71,7 @@ async def get_sitemap(db: AsyncSession | None = Depends(optional_db)):
         '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
         "  <url><loc>https://pyplots.ai/</loc></url>",
         "  <url><loc>https://pyplots.ai/catalog</loc></url>",
+        "  <url><loc>https://pyplots.ai/mcp</loc></url>",
         "  <url><loc>https://pyplots.ai/legal</loc></url>",
     ]
 

app/src/pages/McpPage.tsx

@@ -156,7 +156,7 @@ export function McpPage() {
           <Typography sx={textStyle}>
             <strong>Endpoint</strong>:{' '}
             <code style={{ backgroundColor: '#f3f4f6', padding: '4px 8px', borderRadius: '4px', color: '#3776AB' }}>
-              https://api.pyplots.ai/mcp
+              https://api.pyplots.ai/mcp/
             </code>
           </Typography>
         </Paper>
@@ -179,7 +179,7 @@ export function McpPage() {
               </TableRow>
               <TableRow>
                 <TableCell>URL</TableCell>
-                <TableCell><code>https://api.pyplots.ai/mcp</code></TableCell>
+                <TableCell><code>https://api.pyplots.ai/mcp/</code></TableCell>
               </TableRow>
               <TableRow>
                 <TableCell>Transport</TableCell>
@@ -190,7 +190,7 @@ export function McpPage() {
 
           <Typography sx={subheadingStyle}>Claude Code</Typography>
           <Box sx={codeBlockStyle}>
-            {`claude mcp add pyplots --transport http https://api.pyplots.ai/mcp`}
+            {`claude mcp add pyplots --transport http https://api.pyplots.ai/mcp/`}
           </Box>
 
           <Typography sx={{ ...textStyle, mt: 3 }}>
@@ -318,7 +318,7 @@ export function McpPage() {
               <TableRow>
                 <TableCell>MCP Inspector</TableCell>
                 <TableCell>
-                  <code>npx @modelcontextprotocol/inspector https://api.pyplots.ai/mcp</code>
+                  <code>npx @modelcontextprotocol/inspector https://api.pyplots.ai/mcp/</code>
                 </TableCell>
               </TableRow>
             </TableBody>

docs/reference/mcp.md

@@ -4,7 +4,7 @@
 
 The pyplots MCP (Model Context Protocol) server enables AI assistants and tools to access pyplots programmatically. It provides a standardized interface for searching specifications, fetching implementation code, and integrating pyplots into AI-powered development workflows.
 
-**Endpoint**: `https://api.pyplots.ai/mcp`
+**Endpoint**: `https://api.pyplots.ai/mcp/`
 
 ---
 
@@ -21,7 +21,7 @@ Add to your Claude Desktop config file:
 {
   "mcpServers": {
     "pyplots": {
-      "url": "https://api.pyplots.ai/mcp"
+      "url": "https://api.pyplots.ai/mcp/"
     }
   }
 }
@@ -35,7 +35,7 @@ Add to `.claude/config.json`:
 {
   "mcp": {
     "pyplots": {
-      "url": "https://api.pyplots.ai/mcp"
+      "url": "https://api.pyplots.ai/mcp/"
     }
   }
 }
@@ -421,7 +421,7 @@ api.pyplots.ai
 Test MCP tools directly in your browser:
 
 ```bash
-npx @anthropic-ai/mcp-inspector https://api.pyplots.ai/mcp
+npx @anthropic-ai/mcp-inspector https://api.pyplots.ai/mcp/
 ```
 
 ### 2. Claude Desktop
@@ -436,7 +436,7 @@ npx @anthropic-ai/mcp-inspector https://api.pyplots.ai/mcp
 ```python
 from mcp.client import Client
 
-async with Client("https://api.pyplots.ai/mcp") as client:
+async with Client("https://api.pyplots.ai/mcp/") as client:
     tools = await client.list_tools()
     print(tools)
 
@@ -450,7 +450,7 @@ async with Client("https://api.pyplots.ai/mcp") as client:
 
 ### "MCP server not responding"
 
-1. Check endpoint is accessible: `curl https://api.pyplots.ai/mcp`
+1. Check endpoint is accessible: `curl https://api.pyplots.ai/mcp/`
 2. Verify config file location and syntax
 3. Restart Claude Desktop
 

specs/260129-fix-mcp-trailing-slash-redirect.md

@@ -0,0 +1,136 @@
+# Bug: MCP server 307 redirect breaks Claude CLI integration
+
+## Bug Description
+When users try to add the pyplots MCP server using the Claude CLI command:
+```bash
+claude mcp add pyplots --transport http https://api.pyplots.ai/mcp
+```
+
+The server is added successfully, but when Claude CLI tries to connect, it fails with "Failed to connect" status. The server shows as configured but non-functional.
+
+**Expected behavior**: Claude CLI should successfully connect to the MCP server and list available tools.
+
+**Actual behavior**: Connection fails silently. Running `claude mcp get pyplots` shows `Status: ✗ Failed to connect`.
+
+## Problem Statement
+The pyplots MCP endpoint at `https://api.pyplots.ai/mcp` returns a **307 Temporary Redirect** to `http://api.pyplots.ai/mcp/` when accessed without a trailing slash. This causes two issues:
+
+1. **Claude CLI doesn't follow HTTP redirects** - MCP clients generally do not follow 307 redirects
+2. **HTTPS-to-HTTP downgrade** - The redirect location uses `http://` instead of `https://`, which is a security concern
+
+## Solution Statement
+Update the documentation to instruct users to use the URL with a trailing slash: `https://api.pyplots.ai/mcp/`. This avoids the redirect issue entirely since the server responds correctly when the trailing slash is included.
+
+This is the minimal fix that resolves the issue without requiring code changes to the MCP server or FastAPI configuration.
+
+## Steps to Reproduce
+1. Add the MCP server using Claude CLI:
+   ```bash
+   claude mcp add pyplots --transport http https://api.pyplots.ai/mcp
+   ```
+2. Check the server status:
+   ```bash
+   claude mcp get pyplots
+   ```
+3. Observe: `Status: ✗ Failed to connect`
+
+**Verification that trailing slash works:**
+```bash
+# Remove and re-add with trailing slash
+claude mcp remove pyplots
+claude mcp add pyplots --transport http https://api.pyplots.ai/mcp/
+claude mcp get pyplots
+# Observe: Status should show connected with tools listed
+```
+
+## Root Cause Analysis
+The root cause is a combination of factors:
+
+1. **Starlette/FastAPI redirect behavior**: When an app is mounted at a path, Starlette's router has `redirect_slashes=True` by default. This means requests to `/mcp` are redirected to `/mcp/` with a 307 status code.
+
+2. **MCP client behavior**: Claude CLI (and other MCP clients) do not follow HTTP redirects per the MCP protocol specification. They expect the endpoint to respond directly without redirects.
+
+3. **HTTP downgrade in redirect**: The 307 redirect location header contains `http://` instead of `https://`, likely due to how the request is proxied through Google Cloud Run.
+
+**Technical verification:**
+```bash
+# Without trailing slash - returns 307 redirect
+curl -s -D - https://api.pyplots.ai/mcp 2>&1 | head -5
+# HTTP/2 307
+# location: http://api.pyplots.ai/mcp/
+
+# With trailing slash - works correctly
+curl -s -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" \
+  -X POST -d '{"jsonrpc":"2.0","method":"initialize",...}' https://api.pyplots.ai/mcp/
+# Returns 200 with MCP response
+```
+
+## Relevant Files
+Use these files to fix the bug:
+
+### Existing Files
+- `docs/reference/mcp.md` - MCP documentation that needs URL updates to include trailing slash
+- `app/src/pages/McpPage.tsx` - Frontend MCP page that shows configuration examples
+
+### New Files
+None required.
+
+## Step by Step Tasks
+
+### 1. Update MCP Documentation
+Update `docs/reference/mcp.md` to use trailing slash in all URL examples:
+
+- Change `https://api.pyplots.ai/mcp` to `https://api.pyplots.ai/mcp/` in:
+  - Quick Start section (Claude Desktop config)
+  - Claude Code (CLI) section
+  - MCP Inspector command
+  - Technical Details section
+  - Troubleshooting section (curl command)
+  - Any other occurrences
+
+### 2. Update Frontend MCP Page
+Update `app/src/pages/McpPage.tsx` to use trailing slash in configuration examples:
+
+- Update the JSON configuration examples shown to users
+- Ensure consistency with documentation
+
+### 3. Verify the Fix
+Manually test that the trailing slash URL works:
+
+```bash
+# Remove old config
+claude mcp remove pyplots
+
+# Add with trailing slash
+claude mcp add pyplots --transport http https://api.pyplots.ai/mcp/
+
+# Verify connection works
+claude mcp get pyplots
+# Should show: Status: ✓ Connected (or similar success indicator)
+```
+
+### 4. Run Validation Commands
+Execute all validation commands to ensure no regressions.
+
+## Validation Commands
+Execute every command to validate the bug is fixed with zero regressions.
+
+- `uv run ruff check docs/reference/mcp.md && uv run ruff format docs/reference/mcp.md` - Lint documentation (will pass, md file)
+- `cd app && yarn build` - Verify frontend builds without errors
+- `claude mcp remove pyplots 2>/dev/null; claude mcp add pyplots --transport http https://api.pyplots.ai/mcp/; claude mcp get pyplots` - Test the fix works
+
+## Final Check
+- Use `mcp__plugin_serena_serena__think_about_whether_you_are_done` to verify all tasks are complete.
+
+## Notes
+- **Alternative solutions considered but not chosen:**
+  1. **Disable redirect_slashes in FastAPI**: This would require code changes and may break other parts of the application
+  2. **Register both `/mcp` and `/mcp/` routes**: More complex and requires FastMCP changes
+  3. **Use a different mount pattern**: Would require significant refactoring
+
+- **Future consideration**: If FastMCP or the MCP protocol adds better redirect handling, the server-side fix could be revisited. For now, the documentation fix is the safest and quickest solution.
+
+- **Related issues**:
+  - https://github.com/jlowin/fastmcp/issues/1544
+  - https://github.com/jlowin/fastmcp/issues/1364
+  - https://github.com/modelcontextprotocol/python-sdk/issues/1168

tests/integration/api/test_api_endpoints.py

@@ -12,7 +12,7 @@
 
 from api.cache import clear_cache
 from api.dependencies import get_db
-from api.main import app
+from api.main import app, fastapi_app
 
 
 pytestmark = pytest.mark.integration
@@ -33,14 +33,14 @@ async def client(test_db_with_data):
     async def override_get_db():
         yield test_db_with_data
 
-    app.dependency_overrides[get_db] = override_get_db
+    fastapi_app.dependency_overrides[get_db] = override_get_db
 
     # Patch is_db_configured to return True (it checks env vars, not dependencies)
     with patch("api.dependencies.is_db_configured", return_value=True):
         async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
             yield ac
 
-    app.dependency_overrides.clear()
+    fastapi_app.dependency_overrides.clear()
 
 
 class TestSpecsEndpoints:

tests/unit/api/test_main.py

@@ -12,7 +12,7 @@
 import pytest
 from fastapi.testclient import TestClient
 
-from api.main import app
+from api.main import app, fastapi_app
 from core.database import get_db
 from tests.conftest import TEST_IMAGE_URL, TEST_THUMB_URL
 
@@ -54,7 +54,7 @@ async def mock_get_db():
         yield mock_session
 
     # Override the dependency
-    app.dependency_overrides[get_db] = mock_get_db
+    fastapi_app.dependency_overrides[get_db] = mock_get_db
 
     # Set up the mock to return specs
     mock_result = MagicMock()
@@ -67,7 +67,7 @@ async def mock_get_db():
         yield client
 
     # Clean up
-    app.dependency_overrides.clear()
+    fastapi_app.dependency_overrides.clear()
 
 
 class TestRootEndpoint:
@@ -235,16 +235,16 @@ class TestAppConfiguration:
 
     def test_app_title(self) -> None:
         """App should have correct title."""
-        assert app.title == "pyplots API"
+        assert fastapi_app.title == "pyplots API"
 
     def test_app_version(self) -> None:
         """App should have correct version."""
-        assert app.version == "1.0.0"
+        assert fastapi_app.version == "1.0.0"
 
     def test_app_description(self) -> None:
         """App should have description."""
-        assert "pyplots" in app.description.lower()
-        assert "plotting" in app.description.lower()
+        assert "pyplots" in fastapi_app.description.lower()
+        assert "plotting" in fastapi_app.description.lower()
 
 
 class TestSpecsEndpoint:
@@ -324,12 +324,12 @@ def test_image_has_library_and_url(self, mock_db_client: TestClient) -> None:
 class TestGZipMiddleware:
     """Tests for GZip compression middleware."""
 
-    def test_gzip_middleware_is_configured(self, client: TestClient) -> None:
+    def test_gzip_middleware_is_configured(self) -> None:
         """GZip middleware should be configured in the app."""
         from starlette.middleware.gzip import GZipMiddleware
 
         # Check that GZipMiddleware is in the middleware stack
-        middleware_classes = [m.cls for m in client.app.user_middleware]
+        middleware_classes = [m.cls for m in fastapi_app.user_middleware]
         assert GZipMiddleware in middleware_classes
 
     def test_gzip_not_used_for_small_responses(self, client: TestClient) -> None:
@@ -342,12 +342,12 @@ def test_gzip_not_used_for_small_responses(self, client: TestClient) -> None:
         # Either no encoding or not gzip for small responses
         assert content_encoding is None or content_encoding != "gzip"
 
-    def test_gzip_minimum_size_is_500(self, client: TestClient) -> None:
+    def test_gzip_minimum_size_is_500(self) -> None:
         """GZip middleware should have minimum_size of 500 bytes."""
         from starlette.middleware.gzip import GZipMiddleware
 
         # Find the GZipMiddleware and check its configuration
-        for middleware in client.app.user_middleware:
+        for middleware in fastapi_app.user_middleware:
             if middleware.cls == GZipMiddleware:
                 assert middleware.kwargs.get("minimum_size") == 500
                 break

tests/unit/api/test_routers.py

@@ -9,7 +9,7 @@
 import pytest
 from fastapi.testclient import TestClient
 
-from api.main import app
+from api.main import app, fastapi_app
 from api.routers.plots import (
     _calculate_contextual_counts,
     _calculate_global_counts,
@@ -43,13 +43,13 @@ def db_client():
     async def mock_get_db():
         yield mock_session
 
-    app.dependency_overrides[get_db] = mock_get_db
+    fastapi_app.dependency_overrides[get_db] = mock_get_db
 
     with patch(DB_CONFIG_PATCH, return_value=True):
         client = TestClient(app)
         yield client, mock_session
 
-    app.dependency_overrides.clear()
+    fastapi_app.dependency_overrides.clear()
 
 
 @pytest.fixture