MCP Server Gateway

Overview

This repository is a reference stack for enterprise teams building an MCP gateway and MCP servers from scratch, often inside an air-gapped or restricted network where public SaaS patterns don't apply out of the box. It ships working gateway, server, and agent code that runs locally with Docker, so you can fork and extend it for your own internal tools, identity systems, audit rules, and deployment standards.

It is not a hosted product — it's a starting blueprint: an OAuth-ready gateway, example MCP backends (Artifactory, GitHub, Google Drive), a governed LangGraph agent, PII controls, and the operational pieces (memory, measurement, context control) that production agents usually bolt on later.

Design framework, not just an agent

An agent alone isn't a solution — it needs guardrails around it. Every request that flows through this stack passes through eight design principles, all implemented in Agents/jfrog-agent/:

See Agents/jfrog-agent/README.md for memory backends and environment variables, and context_optimizer for trimming presets.

Quick start

Goal: clone the repo, start Docker, and prove MCP Gateway → MCP server routing works (Artifactory in open mode; GitHub optional with OAuth).

Prerequisites

1. Clone and start the stack

Important: create mcp-gateway/.env and set TOKEN_ENCRYPTION_KEY before docker compose. The setup script does that from .env.example.

git clone https://github.com/harish-gaggar/mcp-server-gateway.git
cd mcp-server-gateway/mcp-gateway

chmod +x scripts/setup-local-env.sh scripts/smoke-test.sh
./scripts/setup-local-env.sh
docker compose up -d --build

Wait until every service is healthy (first build can take several minutes):

docker compose ps

You should see five containers (mcp-gateway, mcp-gateway-redis, artifactory-mcp-server, github-mcp-server, gdrive-mcp-server) with status Up (healthy).

Gateway health check:

curl -s http://localhost:8090/health

Success: JSON contains "status":"ok".

2. Test gateway → MCP server (no OAuth secrets needed)

This checks the gateway proxy to Artifactory MCP (initialize + tools/list) and direct health on all three MCP backends:

./scripts/smoke-test.sh

Success: the script ends with smoke-test: passed and prints a tool count for Artifactory (for example 7 tools).

Manual equivalent (Artifactory only):

node scripts/e2e-test.mjs

3. Optional: GitHub MCP with OAuth (live GitHub API)

Default open mode does not expose the GitHub namespace on the gateway. To test gateway OAuth → GitHub MCP → GitHub API:

1. Create a GitHub OAuth App with callback URL http://localhost:8090/oauth2callback.
2. In mcp-gateway/.env, set:
   • GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET
   • MCP_CONFIG_FILE=./configs/ci-mcp-config.yml
   • OAUTH_CONFIG_FILE=./configs/ci-oauth-config.yml
3. Restart the gateway: docker compose up -d gateway
4. Run (browser login + consent once):

chmod +x scripts/test-github-mcp-oauth.sh
./scripts/test-github-mcp-oauth.sh

Success: tools/list shows GitHub tools and list_repositories returns JSON from your account. See also python3 scripts/oauth-client-demo.py --namespace github --tool get_user_info --args '{"username":"YOUR_GITHUB_LOGIN"}'.

4. Optional: reference agent UI

Start after step 1 (gateway on :8090):

cd ../Agents/jfrog-agent
cp .env.example .env
docker compose up --build

UI: http://localhost:8501. Default memory is SQLite. Spanner emulator: docker compose --profile spanner up --build.

5. Optional: Agent Safety Kit (no Docker)

cd ../../agent-safety-kit
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" && pytest -v

If something fails

Secure mode and full setup

Per-user OAuth (Google, GitHub, Drive), Cursor, and monitoring: doc/howto/QUICKSTART.md and mcp-gateway/.env.example (OAUTH_CONFIG_FILE, MCP_CONFIG_FILE, provider client IDs).

Repository layout

mcp-server-gateway/
├── mcp-gateway/                  # Gateway, Compose, Cursor wrappers
├── artifactory/ github/ gdrive/  # Example MCP servers
├── agent-safety-kit/             # PII and secrets guard (portable)
├── Agents/jfrog-agent/           # Memory, tracking/eval, context optimizer
└── doc/howto/QUICKSTART.md

Verify the stack (contributors and CI)

From a clean clone, the path above (setup-local-env.sh → docker compose up → smoke-test.sh) is the minimum bar.

Full local CI (unit tests + stack + GitHub routing when OAuth creds are set):

chmod +x mcp-gateway/scripts/verify-stack.sh
mcp-gateway/scripts/verify-stack.sh

See CONTRIBUTING.md.

Documentation

Status and license

Reference implementation; APIs may change. Do not commit .env or OAuth secrets.

Licensed under Apache-2.0. Contributions welcome — see CONTRIBUTING.md.