feat: Add multi-user mode with streamable HTTP transport support

[devendershekhawat]

Closes: #471

Overview

This PR introduces a completely new multi-user mode to the GitHub MCP Server, enabling HTTP-based deployments where multiple users can authenticate with their own GitHub tokens per request.

Changes Made

🏗️ New Multi-User Architecture

• Added new multi-user command that starts an HTTP server
• Created MultiUserStreamableHttpServerConfig for multi-user HTTP configuration
• Implemented RunMultiUserStreamableHttpServer function for multi-user HTTP mode
• Added port configuration support with --port flag (defaults to 8080)

🔧 Implementation Details

• HTTP Server Setup: Uses server.NewStreamableHTTPServer() from mcp-go library
• Per-Request Auth: Brand new authentication model with tokens extracted from each request
• Multi-User Toolsets: Created new toolset implementations that handle per-request authentication
• Port Binding: Configurable via command line flag or environment variable
• Error Handling: Proper error propagation and logging for multi-user scenarios

📝 Command Interface

# New multi-user mode with HTTP transport
./github-mcp-server multi-user --port 8080

# Existing single-user modes still work
./github-mcp-server stdio                    # Single-user stdio
./github-mcp-server streamable-http          # Single-user HTTP (if it exists)

🐳 Docker Support

# Updated Dockerfile supports new multi-user HTTP mode
CMD ["./github-mcp-server", "multi-user", "--port", "8080", "--toolsets=repos,issues,users,pull_requests"]

Key Features

👥 Multi-Tenant Support

• No global GitHub token required - tokens provided per request
• Simultaneous users - multiple users can use the server with their own authentication
• Per-request context - each request is handled with the appropriate user's permissions

🌐 Production Ready

• HTTP-based transport for better integration with web services
• Configurable port binding for containerized deployments
• Load balancer friendly - stateless request handling

Testing

✅ Manual Testing

• New multi-user command starts HTTP server correctly
• HTTP server responds on configured port
• Endpoint validation: /mcp endpoint accepts MCP protocol requests
• Port configuration: Custom port binding with --port flag works
• Multi-user auth: Per-request token extraction functions properly
• Backward compatibility: Existing single-user modes unaffected

🧪 Test Commands

# Start multi-user server (no global token needed)
./github-mcp-server multi-user --port 8080

# Test HTTP endpoint with user token in request
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_GITHUB_TOKEN" \
     -d '{"jsonrpc":"2.0","id":"test","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
     http://localhost:8080/mcp

📊 Expected Response

{
  "jsonrpc": "2.0",
  "id": "test",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {},
      "resources": {}
    },
    "serverInfo": {
      "name": "github-mcp-server",
      "version": "dev"
    }
  }
}

Benefits

🌐 Enterprise Ready

1. Multi-Tenant: One server instance can serve multiple users/teams
2. Cloud-Native: Enables containerized deployments with proper HTTP endpoints
3. Scalable: Works seamlessly behind reverse proxies and load balancers
4. Web Integration: Direct HTTP API for web applications and microservices

🔒 Security Model

• ✅ Per-request authentication with individual GitHub tokens
• ✅ No shared credentials or global tokens
• ✅ Each user operates with their own GitHub permissions
• ✅ Stateless request handling for better security

⚡ Performance & Scalability

• 🚀 HTTP transport optimized for distributed scenarios
• 📈 Enables horizontal scaling with multiple server instances
• 🔄 Better integration with modern observability and monitoring tools
• 💫 Stateless architecture supports auto-scaling

Backward Compatibility

• ✅ Existing single-user functionality completely unchanged
• ✅ All existing command line flags preserved
• ✅ No breaking changes to existing deployments
• ✅ New multi-user mode is additive only

Files Changed

Core Implementation

• internal/ghmcp/server.go: Added multi-user server implementation with HTTP support
• cmd/github-mcp-server/main.go: Added new multi-user command with port configuration

Multi-User Toolsets

• Added new multi-user toolset implementations that extract auth tokens from request context
• Created multi-user variants of existing GitHub API integrations

Docker Support

• Dockerfile: Updated to support new multi-user HTTP mode deployments

Architecture Comparison

Before (Single-User Only)

[MCP Client] → [stdio/HTTP] → [GitHub MCP Server] → [GitHub API]
                                    ↑
                              Global GitHub Token

After (Multi-User Option)

[User A] → [HTTP Request + Token A] → [Multi-User Server] → [GitHub API as User A]
[User B] → [HTTP Request + Token B] → [Multi-User Server] → [GitHub API as User B]
[User C] → [HTTP Request + Token C] → [Multi-User Server] → [GitHub API as User C]

Configuration Examples

VS Code MCP Configuration (Multi-User HTTP Mode)

{
  "mcpServers": {
    "github-multi-user": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "8080:8080",
        "ghcr.io/github/github-mcp-server",
        "multi-user", "--port", "8080"
      ]
    }
  }
}

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: github-mcp-server-multi-user
spec:
  replicas: 3
  selector:
    matchLabels:
      app: github-mcp-server-multi-user
  template:
    metadata:
      labels:
        app: github-mcp-server-multi-user
    spec:
      containers:
      - name: github-mcp-server
        image: ghcr.io/github/github-mcp-server:latest
        args: ["multi-user", "--port", "8080"]
        ports:
        - containerPort: 8080
        # Note: No global GitHub token needed for multi-user mode

Future Enhancements

This foundation enables several future improvements:

• 📊 HTTP-based health checks and metrics endpoints
• 🔐 Enhanced authentication mechanisms (OAuth, JWT)
• 📝 OpenAPI specification for the HTTP API
• 🎯 Request routing and user-based rate limiting
• 👥 User session management and caching

Checklist

• Code follows project style guidelines
• Self-review of code completed
• Manual testing performed
• Backward compatibility verified
• Documentation updated (command help)
• Docker support confirmed
• No breaking changes introduced
• New multi-user mode works as expected

Deployment Impact

Zero Risk to Existing Users

• ✅ Completely additive feature - no existing functionality modified
• ✅ Backward compatible - existing single-user deployments unaffected
• ✅ Optional feature - users can continue using existing modes

Rollout Strategy

1. Phase 1: Release new multi-user command as opt-in feature
2. Phase 2: Update documentation with multi-user deployment examples
3. Phase 3: Gather feedback and iterate on multi-user capabilities
4. Phase 4: Consider additional multi-user enhancements based on usage

---

This PR introduces a completely new operational mode that makes the GitHub MCP Server suitable for enterprise and multi-tenant deployments, while maintaining full backward compatibility with existing single-user usage patterns.

[ycjcl868]

I prefer the use of Header Authorization. Is it recommended to use the token as a tool parameter, because the model does not know what the token value is when it is called?

[SamMorrowDrums]

That is true. For http, authorization should only be in headers and sent on every single request as headers, as mentioned. The agent should also not have access to the token.

For transparency, as mentioned previously in response to related issues, we are working on a remote server, and we use this local one as a library, rather than make it work for both.

We will be releasing that soon.

Thank you for the contribution though, it's appreciated. We just will wait for our remote release before we decide what to do here.

[ycjcl868]

That is true. For http, authorization should only be in headers and sent on every single request as headers, as mentioned. The agent should also not have access to the token.

For transparency, as mentioned previously in response to related issues, we are working on a remote server, and we use this local one as a library, rather than make it work for both.

We will be releasing that soon.

Thank you for the contribution though, it's appreciated. We just will wait for our remote release before we decide what to do here.

Will remote server like https://mcp.github.com be released? That's great!

[SamMorrowDrums]

I will leave this hanging until the announcement...

[tonytrg]

@devendershekhawat thank you for the high quality pr 🎆

We have now https://github.com/github/github-mcp-server?tab=readme-ov-file#remote-github-mcp-server released.

[ycjcl868]

@devendershekhawat thank you for the high quality pr 🎆

We have now https://github.com/github/github-mcp-server?tab=readme-ov-file#remote-github-mcp-server released.

bad request: missing required Authorization header, hope listTools can return tool names, request Authorization header when calling the tool.

[tonytrg]

bad request: missing required Authorization header, hope listTools can return tool names, request Authorization header when calling the tool.

@ycjcl868 sorry do you mean, the listTools endpoint should not require authorization?
We currently require authorization on every request, and you can configure dynamically what tools are available on your end https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md

Might this be what you envisioned? If so leave a comment and we can think about implementing it.