KEMBAR78
GitHub - tuannvm/oauth-mcp-proxy: OAuth 2.1 authentication library for Go MCP servers
Skip to content

tuannvm/oauth-mcp-proxy

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OAuth MCP proxy

OAuth 2.1 authentication library for Go MCP servers.

Supports both MCP SDKs:

  • âś… mark3labs/mcp-go
  • âś… modelcontextprotocol/go-sdk (official)

One-time setup: Configure provider + add WithOAuth() to your server. Result: All tools automatically protected with token validation and caching.

mark3labs/mcp-go

import "github.com/tuannvm/oauth-mcp-proxy/mark3labs"

_, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{
    Provider: "okta",
    Issuer:   "https://your-company.okta.com",
    Audience: "api://your-mcp-server",
})

mcpServer := server.NewMCPServer("Server", "1.0.0", oauthOption)

Official SDK

import mcpoauth "github.com/tuannvm/oauth-mcp-proxy/mcp"

mcpServer := mcp.NewServer(&mcp.Implementation{...}, nil)
_, handler, _ := mcpoauth.WithOAuth(mux, cfg, mcpServer)
http.ListenAndServe(":8080", handler)

GitHub Workflow Status Go Version Go Report Card Go Reference GitHub Release License: MIT


Why Use This Library?

  • Dual SDK support - Works with both mark3labs and official SDKs
  • Simple integration - One WithOAuth() call protects all tools
  • Zero per-tool config - All tools automatically protected
  • Fast token caching - 5-min cache, <5ms validation
  • Production ready - Security hardened, battle-tested
  • Multiple providers - HMAC, Okta, Google, Azure AD

How It Works

sequenceDiagram
    participant Client
    participant Your Server
    participant oauth-mcp-proxy
    participant OAuth Provider

    Client->>Your Server: Request with Bearer token
    Your Server->>oauth-mcp-proxy: Validate token
    oauth-mcp-proxy->>OAuth Provider: Check token (cached 5min)
    OAuth Provider->>oauth-mcp-proxy: Valid + user claims
    oauth-mcp-proxy->>Your Server: Authenticated user in context
    Your Server->>Client: Execute protected tool
Loading

What oauth-mcp-proxy does:

  1. Extracts Bearer tokens from HTTP requests
  2. Validates against your OAuth provider (with caching)
  3. Adds authenticated user to request context
  4. All your tools automatically protected

Quick Start

Using mark3labs/mcp-go

1. Install

go get github.com/tuannvm/oauth-mcp-proxy

2. Add to Your Server

import (
    oauth "github.com/tuannvm/oauth-mcp-proxy"
    "github.com/tuannvm/oauth-mcp-proxy/mark3labs"
)

mux := http.NewServeMux()

// Enable OAuth (one time setup)
_, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{
    Provider: "okta",                    // or "hmac", "google", "azure"
    Issuer:   "https://your-company.okta.com",
    Audience: "api://your-mcp-server",
    ServerURL: "https://your-server.com",
})

// Create MCP server with OAuth
mcpServer := mcpserver.NewMCPServer("Server", "1.0.0", oauthOption)

// Add tools - all automatically protected
mcpServer.AddTool(myTool, myHandler)

// Setup endpoint
streamable := mcpserver.NewStreamableHTTPServer(
    mcpServer,
    mcpserver.WithHTTPContextFunc(oauth.CreateHTTPContextFunc()),
)
mux.Handle("/mcp", streamable)

3. Access Authenticated User

func myHandler(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    user, ok := oauth.GetUserFromContext(ctx)
    if !ok {
        return nil, fmt.Errorf("authentication required")
    }
    // Use user.Username, user.Email, user.Subject
}

Using Official SDK

1. Install

go get github.com/modelcontextprotocol/go-sdk
go get github.com/tuannvm/oauth-mcp-proxy

2. Add to Your Server

import (
    "github.com/modelcontextprotocol/go-sdk/mcp"
    oauth "github.com/tuannvm/oauth-mcp-proxy"
    mcpoauth "github.com/tuannvm/oauth-mcp-proxy/mcp"
)

mux := http.NewServeMux()

// Create MCP server
mcpServer := mcp.NewServer(&mcp.Implementation{
    Name:    "my-server",
    Version: "1.0.0",
}, nil)

// Add tools
mcp.AddTool(mcpServer, &mcp.Tool{
    Name: "greet",
    Description: "Greet user",
}, func(ctx context.Context, req *mcp.CallToolRequest, params *struct{}) (*mcp.CallToolResult, any, error) {
    user, _ := oauth.GetUserFromContext(ctx)
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: "Hello, " + user.Username},
        },
    }, nil, nil
})

// Add OAuth protection
_, handler, _ := mcpoauth.WithOAuth(mux, &oauth.Config{
    Provider: "okta",
    Issuer:   "https://your-company.okta.com",
    Audience: "api://your-mcp-server",
}, mcpServer)

http.ListenAndServe(":8080", handler)

Your MCP server now requires OAuth authentication.


Examples

See examples/README.md for detailed setup guide including Okta configuration.

SDK Example Description
mark3labs Simple Minimal setup - copy/paste ready
mark3labs Advanced ConfigBuilder, multiple tools, logging
Official Simple Minimal setup - copy/paste ready
Official Advanced ConfigBuilder, multiple tools, logging

Supported Providers

Provider Best For Setup Guide
HMAC Testing, development docs/providers/HMAC.md
Okta Enterprise SSO docs/providers/OKTA.md
Google Google Workspace docs/providers/GOOGLE.md
Azure AD Microsoft 365 docs/providers/AZURE.md

Documentation

Getting Started:

Advanced:


License

MIT License - See LICENSE

About

OAuth 2.1 authentication library for Go MCP servers

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Packages

No packages published