<div align="center">

MCP Server Gateway

A production-grade MCP Gateway, OAuth-secured MCP servers, and a governed LangGraph agent — ready to fork and run.

Quick Start • Design Principles • Repository Layout • Documentation

</div>

---

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.

<div align="center"> <img width="921" height="369" alt="MCP Server Gateway architecture diagram" src="https://github.com/user-attachments/assets/e2c51646-d205-4d7f-a0ba-7787167175f3" /> </div>

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/:

| # | Principle | What it does | |---|-----------|---------------| | 01 | Agent framework | Task-specific nodes with skills, prompts, and an internal plugin marketplace | | 02 | OAuth before every call | Each MCP tool call runs authenticated, per user | | 03 | Customized MCP | MCP tools tailored to your internal security practices | | 04 | Continuous audit | Every operation is logged at the MCP gateway | | 05 | PII / secrets stripped | Sensitive data is scrubbed before it ever reaches the LLM (agent-safety-kit/) | | 06 | Tracking & eval | Per-query tracking of model, tools, tokens, latency, and response quality | | 07 | Memory management | Conversation threads and LangGraph checkpoints persist across restarts (SQLite by default, Spanner-ready) | | 08 | Context optimizer | Trims and summarizes long MCP transcripts to cut unnecessary token spend while keeping protocol-critical fields |

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

| Requirement | Notes | |-------------|--------| | Docker Desktop or Engine + Compose v2 | Docker must be running before any docker compose command | | Node.js 20+ | Only for the smoke-test scripts (node scripts/…); not required to build images | | Python 3.10+ | Optional: OAuth demo and Agent Safety Kit | | Free ports | 8090 gateway, 8091 Artifactory MCP (direct), 6379 Redis |

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

| Symptom | Fix | |---------|-----| | Cannot connect to the Docker daemon | Start Docker Desktop (or Colima) and retry | | docker pull / x509: certificate signed by unknown authority | Corporate TLS proxy: mcp-gateway/certs/README.md | | invalid IP / host-gateway on Colima | Re-run ./scripts/setup-local-env.sh (sets HOST_DOCKER_INTERNAL) | | Gateway exits on startup | Empty TOKEN_ENCRYPTION_KEY — run ./scripts/setup-local-env.sh before docker compose | | Gateway exits with Google OIDC errors | Use ci-oauth-config.yml for GitHub-only tests, or set GATEWAY_NODE_EXTRA_CA_CERTS per setup script on proxied networks | | smoke-test cannot reach :8090 | docker compose ps — wait for mcp-gateway healthy | | Cursor / HTTPS / monitoring | doc/howto/QUICKSTART.md |

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

| Doc | Topic | |-----|-------| | Contributing | Full verify script and contributor workflow | | Quickstart | OAuth, Cursor, monitoring | | JFrog agent | Memory backends, tracking, env vars | | Context optimizer | Trimming layers and presets | | Agent Safety Kit | Input guard and PII scanner | | Gateway dev | Local dev and tests |

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.

<div align="center">

If this project helps you, consider giving it a ⭐ — it helps others find it too.

</div>