springai -gateway

Spring Boot gateway that unifies multiple MCP servers into one endpoint for AI assistants, OAuth 2.1

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio oalles-springai-mcp-gateway docker run -i springai-mcp-gateway:latest \
  --env MCP_ENDPOINT="https://<your-domain>/mcp" \
  --env AUTH_SERVER_URL="https://<your-domain>/auth" \
  --env PORT_AUTH_SERVER="9090" \
  --env PORT_MCP_GATEWAY="8080"

How to use

This MCP gateway serves as a bridge between MCP clients and the Streamable HTTP MCP server. It exposes the gateway at /mcp, supporting multiple authentication modes (no auth, OAuth 2.1 Client Credentials, and Authorization Code + PKCE). The gateway can route requests from MCP clients such as SSE-based tools (e.g., JetBrains Copilot) and standard stdio-based clients through the same endpoint. To use it, start the Authorization Server and the MCP Gateway, then obtain a Bearer token from the Authorization Server and present it with MCP requests to /mcp. The gateway validates tokens against the public issuer and supports token-based access control for mcp:read and mcp:write scopes. You can leverage Cloudflare Tunnels to expose the public endpoint at a domain, enabling ChatGPT connectors to OAuth flows and token refresh flows automatically.

How to install

Prerequisites:

Java JDK 17+ and Maven installed on your machine
Git to clone the repository
Optional: Docker if you plan to run via Docker image

Installation steps:

Clone the repository: git clone https://github.com/oalles/springai-mcp-gateway.git cd springai-mcp-gateway
Build the project (all modules): mvn -q clean package
Run the Authorization Server (port 9090) and the MCP Gateway (port 8080):
- Using Maven (in separate terminals): mvn -q -pl auth-server spring-boot:run mvn -q -pl mcp-gateway spring-boot:run
Alternatively, run via Docker (if a Docker image is available): docker run -i -p 8080:8080 -p 9090:9090 springai-mcp-gateway:latest
If you’re using Cloudflare Tunnels, follow the CLOUDFLARE.md instructions to set up a tunnel and route /mcp to your local gateway.

Additional notes

Tips and common issues:

Ensure the OAuth 2.1 issuer URL (public domain) is reachable from your clients. If using a local issuer, consider tunneling or exposing it publicly via a Cloudflare Tunnel.
When testing locally, you may use NO_AUTH_SSE branch for a quick integration; switch to OAUTH2.1_STREAMABLE for token-based security and to OAUTH2.1_CHATGPT_TUNNELS for PKCE + public client workflows.
The gateway’s /mcp endpoint supports both SSE and standard HTTP MCP communications; ensure your client is configured to target that path.
For ChatGPT integration, configure the OAuth client as public (no client secret) and let the connector manage tokens and refresh flows.
Always secure your domain with HTTPS and restrict CORS/origin settings in non-demo environments.

Related MCP Servers

mcp-for-beginners

14.5k

This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.

mcphub.nvim

1.7k

An MCP client for Neovim that seamlessly integrates MCP servers into your editing workflow with an intuitive interface for managing, testing, and using MCP servers with your favorite chat plugins.

peta-core

Peta core: The Control Plane for MCP — secure vault, managed runtime, audit trail, and policy-based approvals.

auto -client

基于Spring AI 封装了 mcp-client 服务，目的使web网页智能体也能通过 stdio 和 HTTP SSE（Server-Sent Events）与 MCP Server 进行交互。项目实现了自动化的连接管理机制，包括自动初始化连接、健康检查、超时关闭以及链接复用等功能

slack

Spring AI를 활용한 Slack MCP 서버입니다.

mcp -with-spring-ai

Build your own mcp server with spring ai