S Oauth

Universal OAuth middleware library for MCP (Model Context Protocol) servers with support for any OAuth provider.

Overview

This library provides OAuth authentication for MCP servers using a flexible connector pattern. It handles the complete OAuth flow for any OAuth provider and provides an authenticated /mcp endpoint where you create your own MCP server with tools. Built using the official MCP TypeScript SDK.

Features

• 🔐 Universal OAuth Support - Works with 20+ OAuth providers including GitHub, Google, Slack, and more
• 🔌 Connector Pattern - Pre-built connectors for popular services + easily add support for new OAuth providers
• 🚀 Express Middleware - Simple integration with app.use()
• 🛠️ Bring Your Own MCP Server - Create MCP server in your handler function
• 📊 Session Management - Automatic session handling via MCP SDK
• 🌐 Authenticated Context - Access OAuth tokens in your tools
• 🎯 Production Ready - Built with official MCP SDK components
• 🔑 Minimal Scopes - Uses minimal OAuth scopes for enhanced security

Installation

npm install

Quick Start

Basic Usage

import express from "express"
import { Server } from "@modelcontextprotocol/sdk/server/index.js"
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
import { McpOAuth } from "mcp-s-oauth"
import type { McpOAuthConfig } from "mcp-s-oauth"

const app = express()

// Choose your OAuth provider connector
import { githubConnector } from "mcp-s-oauth"
// or import { googleConnector } from "mcp-s-oauth"
// or create your own custom connector

// Configure OAuth with any provider
const config: McpOAuthConfig = {
  baseUrl: "http://localhost:3000",
  clientId: "your-oauth-client-id",
  clientSecret: "your-oauth-client-secret",
  connector: githubConnector  // or any other connector
}

// Create your MCP handler - this is where YOU create the MCP server
const mcpHandler = async (req: express.Request, res: express.Response, { authInfo }) => {
  // Access the OAuth token from any provider
  const oauthToken = authInfo.token
  
  // Create transport and your MCP server
  const transport = new StreamableHTTPServerTransport(/* options */)
  const mcpServer = new Server({ name: "my-server", version: "1.0.0" })
  
  // Register your tools (customize based on your OAuth provider)
  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [{
      name: "get_profile",
      description: "Get authenticated user profile",
      inputSchema: { type: "object" }
    }]
  }))
  
  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name === "get_profile") {
      // Call your OAuth provider's API using the token
      // Example for GitHub: https://api.github.com/user
      // Example for Google: https://www.googleapis.com/oauth2/v2/userinfo
      const apiUrl = "https://api.github.com/user" // adjust for your provider
      
      const response = await fetch(apiUrl, {
        headers: { "Authorization": `Bearer ${authInfo.token}` }
      })
      const userData = await response.json()
      
      return {
        content: [{ type: "text", text: `Profile: ${JSON.stringify(userData, null, 2)}` }]
      }
    }
  })
  
  // Handle the MCP request
  await mcpServer.connect(transport)
  await transport.handleRequest(req, res, req.body)
}

// Use the library
const mcpOAuth = McpOAuth(config, mcpHandler)
app.use("/", mcpOAuth.router)

app.listen(3000)

OAuth Provider Setup

GitHub OAuth App Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App:
   • Authorization callback URL: ${baseUrl}/oauth/callback (e.g., http://localhost:3000/oauth/callback)
3. Use the Client ID and Secret in your config

Google OAuth App Setup

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the "Google+ API" or "People API"
4. Create OAuth 2.0 credentials:
   • Authorized redirect URIs: ${baseUrl}/oauth/callback (e.g., http://localhost:3000/oauth/callback)
5. Use the Client ID and Secret in your config

Custom OAuth Provider Setup

For any OAuth 2.0 provider, you'll need:

1. Client ID and Client Secret from your provider
2. Authorization callback URL set to: ${baseUrl}/oauth/callback

Available Connectors

This library includes pre-built connectors for popular OAuth providers with minimal scopes for enhanced security:

Service	Connector
Slack	slackConnector
Gmail	gmailConnector
Google Calendar	googleCalendarConnector
Jira	jiraConnector
Trello	trelloConnector
Asana	asanaConnector
Notion	notionConnector
Monday	mondayConnector
GitHub	githubConnector
GitLab	gitlabConnector
Google Workspace	googleWorkspaceConnector
Google Drive	googleDriveConnector
Google Sheets	googleSheetsConnector
Google Forms	googleFormsConnector
Google Slides	googleSlidesConnector
Salesforce	salesforceConnector
Figma	figmaConnector
Zeplin	zeplinConnector
Amplitude	amplitudeConnector
Google Analytics	googleAnalyticsConnector
Google Maps	googleMapsConnector
Discord	discordConnector
Spotify	spotifyConnector
Twitter	twitterConnector

Example Usage with GitHub

import { githubConnector } from "mcp-s-oauth"

const config: McpOAuthConfig = {
  baseUrl: "http://localhost:3000",
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  connector: githubConnector,
}

Custom Connector

For any OAuth provider not listed above:

import type { Connector } from "mcp-s-oauth"

const myCustomConnector: Connector = {
  authUrl: "https://your-provider.com/oauth/authorize",
  tokenUrl: "https://your-provider.com/oauth/token",
  scopes: ["read", "write"],
  codeExchangeConfig: {
    isForm: true,
    modelCredentialsMapping: `{
      "access_token": access_token, 
      "expires_at": $fromMillis($millis() + expires_in * 1000),
      "refresh_token": refresh_token,
      "scope": scope,
      "token_type": token_type
    }`,
  },
  authInitUrlParams: {
    prompt: "consent",
  },
}

Creating Custom Connectors

The Connector interface allows you to integrate any OAuth 2.0 provider. Here's how to create your own:

Connector Interface

export interface Connector {
  authUrl?: string                    // OAuth authorization endpoint
  tokenUrl?: string                   // OAuth token exchange endpoint  
  refreshTokenUrl?: string            // Token refresh endpoint (defaults to tokenUrl)
  scopes?: string[] | readonly string[] // OAuth scopes to request
  codeExchangeConfig?: {
    modelCredentialsMapping?: JsonataString<OAuthCredentials> | ((config: any) => OAuthCredentials)
    isForm?: boolean                  // Use form encoding vs JSON for token exchange
    authorizationMapping?: JsonataString<string> | ((config: any) => string)
  }
  authInitUrlParams?: Record<string, string> // Additional OAuth params
}

Step-by-Step Guide

1. Find OAuth Documentation for your provider (authorization URL, token URL, scopes)

2. Create Connector File:

// src/connectors/my-provider.ts
import type { Connector } from "../types/connector.types.js"

export const myProviderConnector: Connector = {
  authUrl: "https://api.myprovider.com/oauth/authorize",
  tokenUrl: "https://api.myprovider.com/oauth/token", 
  scopes: ["read", "write"],
  codeExchangeConfig: {
    isForm: true, // Most providers use form encoding
    modelCredentialsMapping: `{
      "access_token": access_token, 
      "expires_at": $fromMillis($millis() + expires_in * 1000),
      "refresh_token": refresh_token,
      "scope": scope,
      "token_type": token_type
    }`,
  },
}

3. Handle Special Cases:

// Provider requires special auth parameters
export const specialProviderConnector: Connector = {
  authUrl: "https://special.com/oauth/authorize",
  tokenUrl: "https://special.com/oauth/token",
  scopes: ["user:read"],
  authInitUrlParams: {
    access_type: "offline",
    prompt: "consent",
    response_mode: "query",
  },
  codeExchangeConfig: {
    isForm: false, // This provider uses JSON
  },
}

4. Use Function for Complex Mapping:

export const complexProviderConnector: Connector = {
  authUrl: "https://complex.com/oauth/authorize",
  tokenUrl: "https://complex.com/oauth/token",
  scopes: ["api"],
  codeExchangeConfig: {
    isForm: true,
    // Use function for complex response mapping
    modelCredentialsMapping: (tokenResponse) => ({
      access_token: tokenResponse.accessToken, // Different field name
      expires_at: new Date(Date.now() + tokenResponse.expiresIn * 1000).toISOString(),
      refresh_token: tokenResponse.refreshToken,
      refresh_token_expires_at: null,
      scope: tokenResponse.scope,
      token_type: "Bearer",
    }),
  },
}

Common OAuth Patterns

Provider	Auth URL	Token URL	Form Encoding	Special Notes
GitHub	/login/oauth/authorize	/login/oauth/access_token	❌ JSON	Simple flow
Google	/o/oauth2/v2/auth	/oauth2/token	✅ Form	Use access_type: offline
Discord	/api/oauth2/authorize	/api/oauth2/token	✅ Form	Standard OAuth
Twitter	/i/oauth2/authorize	/2/oauth2/token	✅ Form	Requires PKCE
LinkedIn	/authorization	/accessToken	✅ Form	Different field names

Testing Your Connector

1. Create test config:

const config: McpOAuthConfig = {
  baseUrl: "http://localhost:3000",
  clientId: process.env.MY_PROVIDER_CLIENT_ID!,
  clientSecret: process.env.MY_PROVIDER_CLIENT_SECRET!,
  connector: myProviderConnector,
}

2. Test OAuth flow:

   • Visit /auth/authorize
   • Complete OAuth on provider
   • Check console logs for token exchange
   • Test API calls with the token

3. Common Issues:

   • Form vs JSON: Check provider docs for token endpoint format
   • Field Names: Response might use different field names
   • Scopes: Ensure scopes are valid for your provider
   • Callback URL: Must match OAuth app configuration

Example Tools Implementation

The tools you create depend on your OAuth provider and their APIs. The library provides the OAuth token - you implement the tools. Here's a complete GitHub example:

GitHub Tools Example

// In your mcpHandler function
mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "github_me",
      description: "Get authenticated user's GitHub profile",
      inputSchema: { type: "object", properties: {} }
    },
    {
      name: "github_repos",
      description: "List user's repositories",
      inputSchema: { 
        type: "object",
        properties: {
          type: { type: "string", enum: ["all", "owner", "member"] }
        }
      }
    },
    {
      name: "github_issues",
      description: "List user's issues",
      inputSchema: { 
        type: "object",
        properties: {
          state: { type: "string", enum: ["open", "closed", "all"] }
        }
      }
    }
  ]
}))

mcpServer.setRequestHandler(CallToolRequestSchema, async (request, { authInfo }) => {
  if (request.params.name === "github_me") {
    const response = await fetch("https://api.github.com/user", {
      headers: { "Authorization": `Bearer ${authInfo.token}` }
    })
    return { content: [{ type: "text", text: await response.text() }] }
  }
  
  if (request.params.name === "github_repos") {
    const { type = "all" } = request.params.arguments || {}
    const response = await fetch(`https://api.github.com/user/repos?type=${type}`, {
      headers: { "Authorization": `Bearer ${authInfo.token}` }
    })
    return { content: [{ type: "text", text: await response.text() }] }
  }

  if (request.params.name === "github_issues") {
    const { state = "open" } = request.params.arguments || {}
    const response = await fetch(`https://api.github.com/issues?state=${state}`, {
      headers: { "Authorization": `Bearer ${authInfo.token}` }
    })
    return { content: [{ type: "text", text: await response.text() }] }
  }
})

Other Provider Examples

For other OAuth providers, follow the same pattern using their respective APIs:

• Slack: Use https://slack.com/api/ endpoints
• Google Services: Use Google API endpoints (Gmail, Drive, Sheets, etc.)
• Notion: Use https://api.notion.com/v1/ endpoints
• Jira: Use Atlassian REST API endpoints
• And more... - Each connector works with the provider's standard OAuth API

MCP Client Usage

Using with MCP Clients

Your OAuth-authenticated MCP server implements the MCP (Model Context Protocol) and can be used with any MCP-compatible client:

import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"

const client = new Client({
  name: "oauth-mcp-client",
  version: "1.0.0"
})

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp")
)

await client.connect(transport)

// List available tools (depends on your implementation)
const tools = await client.listTools()
console.log("Available tools:", tools)

// Call any tool you've implemented
const result = await client.callTool({
  name: "get_profile", // or any tool name you've implemented
  arguments: {}
})
console.log("Result:", result)

Authentication Flow

1. Start OAuth Flow: Make a request to /auth/authorize to initiate OAuth with your provider
2. User Authorization: User is redirected to OAuth provider to authorize your application
3. Token Exchange: Provider redirects back with an authorization code
4. MCP Access: Use the obtained token to make authenticated MCP requests to /mcp

API Reference

Server Information

• GET / - Server information, available tools, and authentication endpoints
• GET /health - Health check endpoint

Authentication Endpoints

• POST /auth/authorize - Start OAuth flow with configured provider
• POST /auth/token - Exchange authorization code for access token
• GET /oauth/callback - OAuth callback handler (used by the provider)

MCP Protocol

• ALL /mcp - Main MCP endpoint supporting all MCP protocol methods
  • Requires Bearer token authentication
  • Supports session management with mcp-session-id header
  • Handles tools/list and tools/call requests
  • Returns tools you've implemented in your mcpHandler

Testing the Server

Test the MCP server using the official SDK client:

import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"

// Connect to the server
const client = new Client({ name: "test-client", version: "1.0.0" })
const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp"),
  {
    requestInit: {
      headers: {
        'Authorization': 'Bearer your-oauth-token-here'
      }
    }
  }
)

await client.connect(transport)

// Test listing tools
const tools = await client.listTools()
console.log("Available tools:", tools.tools)

// Test calling any tool you've implemented
const result = await client.callTool({
  name: "get_profile", // or any tool name you've implemented
  arguments: {}
})
console.log("Result:", result.content)

Development

Project Structure

src/
├── index.ts               # Library exports
├── server.ts              # MCP server implementation  
├── lib.ts                 # Core utilities
├── connectors/            # OAuth provider connectors
├── services/              # Database & auth services
└── types/                 # TypeScript types

Building and Running

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Adding New Tools

To add new MCP tools to your server:

1. Update the tools list in ListToolsRequestSchema handler
2. Add tool implementation in CallToolRequestSchema handler
3. Use the OAuth token to call your provider's APIs

Example (provider-agnostic):

// In ListToolsRequestSchema handler
{
  name: "get_user_data",
  description: "Get user data from OAuth provider",
  inputSchema: {
    type: "object",
    properties: {
      fields: {
        type: "array",
        items: { type: "string" },
        description: "Fields to retrieve"
      }
    }
  }
}

// In CallToolRequestSchema handler
if (name === "get_user_data") {
  const { fields = [] } = request.params.arguments || {}
  
  // Use the OAuth token to call your provider's API
  const apiUrl = "https://api.your-provider.com/user" // adjust for your provider
  const response = await fetch(apiUrl, {
    headers: {
      "Authorization": `Bearer ${authInfo.token}`,
      "Accept": "application/json"
    }
  })
  
  const userData = await response.json()
  
  return {
    content: [{ 
      type: "text", 
      text: JSON.stringify(userData, null, 2)
    }]
  }
}

Security Considerations

1. OAuth Secrets: Never commit OAuth client secrets to version control
2. HTTPS: Use HTTPS in production for secure OAuth flows
3. Environment Variables: Store all sensitive configuration in environment variables
4. Token Storage: Tokens are managed by the MCP SDK OAuth provider
5. OAuth App Configuration: Configure your OAuth app with correct callback URLs
6. Scope Limitation: Request only the OAuth scopes your application needs
7. Token Validation: The library handles token validation automatically

Troubleshooting

Common Issues

1. "Missing required environment variables"

   • Ensure your OAuth provider's CLIENT_ID and CLIENT_SECRET are set
   • Check environment variable names match your configuration

2. OAuth callback errors

   • Verify your BASE_URL matches your OAuth app configuration
   • Check that Authorization callback URL is set to ${baseUrl}/oauth/callback
   • Ensure your OAuth provider app is configured correctly

3. Token exchange errors

   • Check isForm setting in your connector - most providers use form encoding
   • Verify tokenUrl is correct for your provider
   • Check if provider requires special headers or parameters

4. API rate limits

   • Authenticated requests usually have higher rate limits
   • Consider implementing caching for frequently accessed data
   • Check your provider's rate limiting documentation

5. MCP client connection issues

   • Ensure you're using the correct MCP endpoint URL: /mcp
   • Verify Bearer token authentication is properly configured
   • Check that your tools are properly registered in the mcpHandler

6. Connector issues

   • Verify OAuth URLs are correct for your provider
   • Check scopes are valid for your provider
   • Test OAuth flow manually in browser first

Debug Mode

Enable detailed logging by setting environment variables:

DEBUG=mcp:*
NODE_ENV=development

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

MIT License - see LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

Related Projects

• Model Context Protocol
• MCP Servers
• Express.js

Hosted Solution

Visit webrix.ai for our fully managed hosting solution with advanced features:

Zero Configuration: Get started in seconds without any setup Enterprise-grade Security: Advanced SSO authentication for all MCP interactions 20+ Pre-built Connectors: Fast plug-and-play integration with hundreds of tools Roles & Permissions: Granular access control with custom role definitions Monitoring & Analytics: Real-time insights into your MCP usage High Availability: 99.9% uptime SLA with global CDN Premium Support: Direct access to our engineering team Custom Integrations: Build and deploy custom MCP connectors