MCP-S Gateway

---

MCP-S Gateway

mcp-gateway is a secure gateway and integration layer for the Model Context Protocol (MCP). It provides a unified, enterprise-ready interface for connecting, managing, and extending MCP modules and services, with a focus on security and seamless integration.

Quick Start

1. Configure your MCP servers - Create mcp.json file in your project:

{
  "mcpServers": {
    "your-server": {
      "command": "npx",
      "args": ["-y", "@your-mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    },
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp"]
    }
  }
}

2. Use the .env.example file as a base, and override as needed:

3. Start with npx (Recommended):

# Default (uses ./mcp.json and ./.env)
npx @mcp-s/secure-mcp-gateway

# Custom configuration paths
npx @mcp-s/secure-mcp-gateway --mcp-config ./custom/mcp.json --envfile ./custom/.env

Or clone:

git clone https://github.com/mcp-s-ai/secure-mcp-gateway.git && cd secure-mcp-gateway
npm install && npm run start

4. Add to your MCP configuration:

stdio:

{
  "mcpServers": {
    "mcp-gateway": {
      "command": "npx",
      "args": ["-y", "@mcp-s/mcp"],
      "env": {
        "BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Streamable HTTP Configuration:

{
  "mcpServers": {
    "mcp-gateway": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Features

• Self-Hosted Gateway: Deploy within your own infrastructure for maximum control
• OAuth Authentication: Secure authentication with any OAuth provider via Auth.js
• TypeScript Support: Fully typed for robust development

Supports all MCP Connection Types:

• STDIO: Standard input/output MCP servers

• StreamableHTTP: HTTP-based streaming connections via http://localhost:3000/mcp (or https://<your-domain>/mcp for hosted deployments)

  Server Selection: You can connect to a specific MCP server by adding the ?server_name=XXX query parameter, where XXX is the name of the server from your mcp.json configuration. For example: http://localhost:3000/mcp?server_name=your-server

  Connect with your preferred AI client:

  Client	Link
  Claude	claude.ai
  Cursor	cursor.com
  Windsurf	codeium.com/windsurf
  VSCode	code.visualstudio.com
  Cline	cline.tools
  Highlight AI	highlightai.com
  Augment Code	augmentcode.com

Deploy

Deploy the mcp-s gateway using npx:

1. Set up your environment variables (see Advanced Configuration)
2. Create your mcp.json configuration file
3. Run npx @mcp-s/secure-mcp-gateway

For production deployments, consider using:

• Process managers like PM2: pm2 start "npx @mcp-s/secure-mcp-gateway" --name mcp-gateway
• Container orchestration (Docker, Kubernetes)
• Cloud platforms (Heroku, Railway, Render)

Authentication Setup

mcp-gateway leverages the power of Auth.js, which supports 80+ OAuth providers out of the box. This makes Auth.js the perfect companion for an open-source project like mcp-gateway. Both libraries share the same commitment to flexibility, security, and developer experience. By integrating with Auth.js, we avoid reinventing authentication wheels and instead provide you with battle-tested, production-ready OAuth flows that work seamlessly across providers.

Simply set the AUTH_PROVIDER environment variable and provide the required credentials for your chosen provider - mcp-gateway handles the rest.

Documentation: Auth.js Google Provider

AUTH_SECRET=your-random-secret
AUTH_PROVIDER=google
AUTH_GOOGLE_ID=your-google-client-id
AUTH_GOOGLE_SECRET=your-google-client-secret

Documentation: Auth.js Okta Provider

AUTH_SECRET=your-random-secret
AUTH_PROVIDER=okta
AUTH_OKTA_ID=your-okta-client-id
AUTH_OKTA_SECRET=your-okta-client-secret
AUTH_OKTA_ISSUER=https://your-okta-domain.okta.com/oauth2/default

Documentation: Auth.js Azure AD Provider

AUTH_SECRET=your-random-secret
AUTH_PROVIDER=azure-ad
AUTH_AZURE_AD_ID=your-azure-client-id
AUTH_AZURE_AD_SECRET=your-azure-client-secret
AUTH_AZURE_AD_TENANT_ID=your-tenant-id-or-common

Documentation: Auth.js GitHub Provider

GitHub OAuth is particularly useful for MCP servers that interact with GitHub repositories, such as Octocode. When using GitHub OAuth, you can specify scopes to control what permissions your MCP servers have access to.

AUTH_SECRET=your-random-secret
AUTH_PROVIDER=github
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret
AUTH_GITHUB_SCOPES=repo

Common GitHub Scopes:

• repo - Full access to repositories (public and private)
• public_repo - Access to public repositories only
• read:user - Read access to user profile information
• user:email - Access to user email addresses

For Octocode and similar MCP servers that need repository access, the repo scope is typically required.

For other providers, see the Auth.js Providers documentation.

Advanced Configuration

Command Line Options

Option	Description	Default Value	Example
--mcp-config	Path to MCP servers configuration file	./mcp.json	--mcp-config ./config/servers.json
--envfile	Path to environment variables file	./.env	--envfile ./config/production.env

Environment Variables

Environment Variable	Description	Default Value	Required
PORT	Server port	3000	No
BASE_URL	Base URL for the gateway	http://localhost:3000	No
AUTH_SECRET	Secret for signing/encrypting tokens (generate with openssl rand -base64 33)	-	Yes
AUTH_PROVIDER	OAuth provider name	google	No
TOKEN_EXPIRATION_TIME	Token expiration time in milliseconds	86400000 (24h)	No
DB_PATH	SQLite database file path	./mcp.sqlite	No
AUTH_[Provider]_ID	OAuth client ID for your provider	-	Yes
AUTH_[Provider]_SECRET	OAuth client secret for your provider	-	Yes
AUTH_[Provider]_*	Additional provider-specific variables (see Auth.js documentation)	-	Varies

Troubleshooting

Issue: When using StreamableHTTP configuration in Cursor, tools don't appear even after successful authentication.

Solution: Make sure you have only one Cursor window open. Multiple Cursor windows can interfere with the MCP connection establishment.

1. Close all Cursor windows
2. Open a single Cursor window
3. Retry the authentication process

Issue: You see the following error:

Error [ERR_UNKNOWN_BUILTIN_MODULE]: No such built-in module: node:sqlite

Solution: This error occurs when using an older version of Node.js. The node:sqlite module requires Node.js version 22 or higher.

Fix:

1. Update Node.js to version 22 or later
2. Verify your version: node --version
3. Restart the gateway: npm run start

Installation options:

• Using nvm: nvm install 22 && nvm use 22
• Download from nodejs.org

Hosted Solution

Visit mcp-s.com 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

Community

Have questions? Need help getting started? Want to share your MCP setup?

Join our Slack community where developers are actively helping each other with MCP gatway implementations, troubleshooting, and sharing best practices.

💬 Join our Slack community →

License

Released under the MIT License. Contributions welcome - star & fork!