mcp-context-forge

# MCP Gateway

> Model Context Protocol gateway & proxy - unify REST, MCP, and A2A with federation, virtual servers, retries, security, and an optional admin UI.

![ContextForge Banner](docs/docs/images/contextforge-banner.png)

## Badges

### CI / Security / Build

[![Build Python Package](https://github.com/IBM/mcp-context-forge/actions/workflows/python-package.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/python-package.yml)
[![CodeQL](https://github.com/IBM/mcp-context-forge/actions/workflows/codeql.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/codeql.yml)
[![Bandit Security](https://github.com/IBM/mcp-context-forge/actions/workflows/bandit.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/bandit.yml)
[![Dependency Review](https://github.com/IBM/mcp-context-forge/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/dependency-review.yml)
[![Tests & Coverage](https://github.com/IBM/mcp-context-forge/actions/workflows/pytest.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/pytest.yml)
[![Lint & Static Analysis](https://github.com/IBM/mcp-context-forge/actions/workflows/lint.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/lint.yml)

### Container Build & Deploy

[![Secure Docker Build](https://github.com/IBM/mcp-context-forge/actions/workflows/docker-image.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/docker-image.yml)
[![Deploy to IBM Code Engine](https://github.com/IBM/mcp-context-forge/actions/workflows/ibm-cloud-code-engine.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/ibm-cloud-code-engine.yml)

### Package / Container

[![Async](https://img.shields.io/badge/async-await-green.svg)](https://docs.python.org/3/library/asyncio.html)
[![License](https://img.shields.io/github/license/ibm/mcp-context-forge)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/mcp-contextforge-gateway)](https://pypi.org/project/mcp-contextforge-gateway/)
[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fibm%2Fmcp--context--forge-blue)](https://github.com/ibm/mcp-context-forge/pkgs/container/mcp-context-forge)

## Introduction

ContextForge MCP Gateway is a feature-rich gateway, proxy, and MCP Registry designed to federate Model Context Protocol (MCP) and REST services. It unifies discovery, authentication, rate-limiting, observability, virtual servers, multi-transport protocols, and an optional Admin UI into a single, clean endpoint for your AI clients.  It operates as a fully compliant MCP server, deployable via PyPI or Docker, and scales to multi-cluster environments on Kubernetes with Redis-backed federation and caching.

![MCP Gateway](https://ibm.github.io/mcp-context-forge/images/mcpgateway.gif)

---

## Table of Contents

- [🚀 Overview & Goals](#-overview--goals)
- [Quick Start](#quick-start)
  - [PyPI](#pypi)
    - [Installation and Running](#installation-and-running)
  - [Containers](#containers)
    - [Docker](#docker)
      - [Minimum Viable Run](#minimum-viable-run)
      - [Persisting the SQLite Database](#persisting-the-sqlite-database)
      - [Local Tool Discovery (Host Network)](#local-tool-discovery-host-network)
    - [Podman (Rootless-Friendly)](#podman-rootless-friendly)
      - [Basic Run](#basic-run)
      - [Persisting SQLite](#persisting-sqlite)
      - [Host Networking (Rootless)](#host-networking-rootless)
- [Testing the `mcpgateway.wrapper`](#testing-the-mcpgatewaywrapper)
  - [Running from an MCP Client](#running-from-an-mcp-client)
    - [Install `uv`](#install-uv)
    - [Create a Virtual Environment and Run the Wrapper](#create-a-virtual-environment-and-run-the-wrapper)
    - [Claude Desktop JSON Configuration](#claude-desktop-json-configuration)
  - [Using with Claude Desktop (or any GUI MCP client)](#using-with-claude-desktop-or-any-gui-mcp-client)
- [VS Code Dev Container Quick Start](#vs-code-dev-container-quick-start)
  - [Clone and Open](#clone-and-open)
  - [First-Time Build (Automatic)](#first-time-build-automatic)
- [Manual Installation](#manual-installation)
  - [Prerequisites](#prerequisites-1)
  - [One-Liner (Development)](#one-liner-development)
  - [Containerized (Self-Signed TLS)](#containerized-self-signed-tls)
  - [Smoke Test the API](#smoke-test-the-api)
- [Installation](#installation-1)
  - [Via Make](#via-make-1)
  - [UV (Alternative)](#uv-alternative-1)
  - [pip (Alternative)](#pip-alternative-1)
  - [Optional: PostgreSQL Adapter](#optional-postgresql-adapter)
    - [Quick PostgreSQL Container](#quick-postgresql-container)
- [Configuration](#configuration)
  - [Basic](#basic-1)
  - [Authentication](#authentication-1)
  - [UI Features](#ui-features-1)
  - [Security](#security-1)
  - [Logging](#logging-1)
  - [Transport](#transport-1)
  - [Federation](#federation-1)
  - [Resources](#resources-1)
  - [Tools](#tools-1)
  - [Prompts](#prompts-1)
  - [Health Checks](#health-checks-1)
  - [Database](#database-1)
  - [Cache Backend](#cache-backend-1)
  - [Development](#development-1)
- [Running](#running-1)
  - [Makefile](#makefile-1)
  - [Script Helper](#script-helper-1)
  - [Manual (Uvicorn)](#manual-uvicorn-1)
- [Authentication Examples](#authentication-examples-1)
- [☁️ AWS / Azure / OpenShift](#️-aws--azure--openshift-1)
- [☁️ IBM Cloud Code Engine Deployment](#️-ibm-cloud-code-engine-deployment-1)
  - [Prerequisites](#-prerequisites-1)
  - [Environment Variables](#-environment-variables-1)
  - [Make Targets](#-make-targets-1)
  - [Example Workflow](#-example-workflow-1)
- [API Endpoints](#api-endpoints-1)
- [Testing](#testing-1)
- [Project Structure](#project-structure-1)
- [API Documentation](#api-documentation-1)
- [Makefile Targets](#makefile-targets-1)
- [Troubleshooting](#-troubleshooting-1)
  - [Diagnose the Listener](#diagnose-the-listener-1)
  - [Why localhost Fails on Windows](#why-localhost-fails-on-windows-1)
    - [Fix (Podman Rootless)](#fix-podman-rootless-1)
    - [Fix (Docker Desktop > 4.19)](#fix-docker-desktop--419-1)
- [Contributing](#contributing-1)
- [Changelog](#changelog-1)
- [License](#license-1)
- [Core Authors and Maintainers](#core-authors-and-maintainers-1)
- [Star History and Project Activity](#star-history-and-project-activity-1)

## 🚀 Overview & Goals

The **ContextForge MCP Gateway** acts as a production-grade gateway, registry, and proxy, positioned in front of any [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server or REST API. It exposes a unified endpoint for all your AI clients, simplifying integration and management.

Key features include:

*   **