feat: Add authentication to the endpoints

[pablotp]

Add authentication support

Summary

Adds optional API key authentication to protect /sse and /mcp endpoints. Authentication is disabled by default for backward compatibility.

Changes

• Added AuthMiddleware class for API key validation
• Added --api-key CLI argument and MCP_PROXY_API_KEY environment variable support
• Protected endpoints: /sse, /mcp, /messages/* (including named server paths)
• Unprotected endpoints: /status, OPTIONS requests

Usage

# Start server with authentication
mcp-proxy --port 8080 --api-key YOUR_SECRET_KEY uvx mcp-server-fetch

# Make authenticated request
curl -H "X-API-Key: YOUR_SECRET_KEY" http://localhost:8080/sse

Testing

• Added comprehensive test suite covering authentication scenarios. All tests pass.
• Manual tests:

Manual verification commands

Make sure you have installed dependencies:

uv sync

Test 1: Server WITHOUT Authentication

Open Terminal 1 and start the server:

uv run mcp-proxy --port 8080 echo "Hello MCP"

Open Terminal 2 and test endpoints:

# Should return 200 (status endpoint)
curl -i http://localhost:8080/status

# Should return 200 or 405 (SSE endpoint - no auth required)
curl -i http://localhost:8080/sse

Test 2: Server WITH Authentication (CLI argument)

Open Terminal 1 and start the server with API key:

uv run mcp-proxy --port 8080 --api-key test123 echo "Hello MCP"

Open Terminal 2 and test endpoints:

# Status endpoint (should work without auth - returns 200)
curl -i http://localhost:8080/status

# SSE endpoint WITHOUT API key (should return 401)
curl -i http://localhost:8080/sse

# SSE endpoint with WRONG API key (should return 401)
curl -i -H "X-API-Key: wrong" http://localhost:8080/sse

# SSE endpoint with CORRECT API key (should return 200 or 405)
curl -i -H "X-API-Key: test123" http://localhost:8080/sse

# Test case-insensitive header (should work)
curl -i -H "x-api-key: test123" http://localhost:8080/sse

Test 3: Server WITH Authentication (Environment Variable)

Open Terminal 1 and start the server with env var:

export MCP_PROXY_API_KEY=secret123
uv run mcp-proxy --port 8080 echo "Hello MCP"

Open Terminal 2 and test:

# Without key (should return 401)
curl -i http://localhost:8080/sse

# With correct key from env (should return 200 or 405)
curl -i -H "X-API-Key: secret123" http://localhost:8080/sse

Test 4: Named Server Endpoints

Start server with named servers and authentication:

uv run mcp-proxy --port 8080 --api-key test123 --named-server test1 "echo test1" echo "default"

Test in another terminal:

# Named server SSE endpoint without key (should return 401)
curl -i http://localhost:8080/servers/test1/sse

# Named server SSE endpoint with key (should work)
curl -i -H "X-API-Key: test123" http://localhost:8080/servers/test1/sse

Expected Results

• Without authentication: All endpoints are accessible
• With authentication:
  • /status always accessible
  • /sse and /mcp require valid API key
  • Wrong or missing key returns 401
  • Correct key allows access
  • Headers are case-insensitive
  • Named server endpoints also protected

Related

• GH Issue: Add API key authentication to secure proxy endpoints #108
• Reference: feat: Add authentication to the endpoints punkpeye/mcp-proxy#34
• Previous attempt: Add optional Authorization header token-based authentication when serving mcp via SSE #58%

[codecov]

Codecov Report

❌ Patch coverage is 98.35165% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/mcp_proxy/auth.py	92.00%	1 Missing and 1 partial ⚠️
src/mcp_proxy/mcp_server.py	98.03%	0 Missing and 1 partial ⚠️

@@            Coverage Diff             @@
##             main     #107      +/-   ##
==========================================
+ Coverage   97.20%   97.42%   +0.22%     
==========================================
  Files           6        8       +2     
  Lines         823      972     +149     
  Branches       30       36       +6     
==========================================
+ Hits          800      947     +147     
- Misses         15       16       +1     
- Partials        8        9       +1     

Files with missing lines	Coverage Δ
tests/test_auth_simple.py	100.00% <100.00%> (ø)
tests/test_mcp_server.py	99.30% <100.00%> (+0.04%)	⬆️
src/mcp_proxy/mcp_server.py	93.91% <98.03%> (+1.12%)	⬆️
src/mcp_proxy/auth.py	92.00% <92.00%> (ø)

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 85bf96c...218da4f. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sparfenyuk]

Hey @pablotp, nice contribution! Can you resolve failures in the build checks?

[pablotp]

@sparfenyuk I'm sorry for not looking more carefully into the pre-commits and test setup. I've just pushed a commit to address the issues and resolve the conflicts with main. Locally, the different steps of the pipeline work. Please trigger the GHA build at your earliest convenience.

[pablotp]

@sparfenyuk it seems a file outside of my PR caused an error for the linter. I've pushed a new commit to address this: 218da4f
I hope that's the last one needed to get the build green :-)

Thanks for your prompt response!

[sparfenyuk]

@pablotp Thank you, and no worries - all good!