# 468 Index Ed616467 > ContextForge MCP Gateway - Frequently Asked Questions - Skill: `tools-only/468-index-ed616467` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/468-index-ed616467` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/468-index-ed616467/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/468-index-ed616467 --- # ContextForge MCP Gateway - Frequently Asked Questions ## ⚑ Quickstart ???+ example "πŸš€ How can I install and run MCP Gateway in one command?" PyPI (pipx / uvx makes an isolated venv): ```bash # Using pipx - pip install pipx pipx run --spec mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444 # Or uvx - pip install uv (default login: admin@example.com/changeme) uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444 ``` OCI image (Docker/Podman) - shares host network so localhost works: ```bash podman run --network=host -p 4444:4444 ghcr.io/ibm/mcp-context-forge:1.0.0-RC-1 ``` ???+ example "πŸ—‚οΈ What URLs are available for the admin interface and API docs?" - Admin UI β†’ `http://localhost:4444/admin` (or `http://localhost:8080/admin` with Compose) - Swagger β†’ `http://localhost:4444/docs` (JWT-protected by default) - ReDoc β†’ `http://localhost:4444/redoc` (JWT-protected by default) !!! tip Log in to the Admin UI to get a session cookie, or enable `DOCS_ALLOW_BASIC_AUTH=true` for Basic auth access to `/docs` and `/redoc`. --- ## πŸ€” What is MCP (Model Context Protocol)? ???+ info "πŸ’‘ What is MCP in a nutshell?" MCP is an open-source protocol released by Anthropic in Nov 2024 that lets language models invoke external tools via a typed JSON-RPC envelope. Community folks call it "USB-C for AI"-one connector for many models. ???+ info "🌍 Who supports MCP and what's the ecosystem like?" - Supported by GitHub & Microsoft Copilot, AWS Bedrock, Google Cloud Vertex AI, IBM watsonx, AgentBee, LangChain, CrewAI and 15,000+ community servers. - Contracts enforced via JSON Schema. - Multiple transports (STDIO, SSE, HTTP) - still converging. --- ## 🧰 Media Kit ???+ tip "πŸ–ΌοΈ I want to make a social media post, where can I find samples and logos?" See the provided [media kit](../media/index.md) ???+ tip "πŸ“„ How do I describe the gateway in boilerplate copy?" > "ContextForge MCP Gateway is an open-source reverse-proxy that unifies MCP and REST tool servers under a single secure HTTPS endpoint with discovery, auth and observability baked in." --- ## πŸ› οΈ Installation & Configuration ???+ example "πŸ”§ What is the minimal .env setup required?" ```bash cp .env.example .env ``` Then edit: ```env # JWT authentication (required) JWT_SECRET_KEY=my-test-key # Admin UI login credentials PLATFORM_ADMIN_EMAIL=admin@example.com PLATFORM_ADMIN_PASSWORD=changeme ``` !!! info "Authentication" The Admin UI uses email/password authentication. Basic auth for API endpoints is disabled by default for security. Use JWT tokens for API access. ???+ example "πŸͺ› What are some advanced environment variables I can configure?" - Basic: `HOST`, `PORT`, `APP_ROOT_PATH` - Auth: `AUTH_REQUIRED`, `BASIC_AUTH_*`, `JWT_SECRET_KEY` - Logging: `LOG_LEVEL`, `LOG_FORMAT`, `LOG_TO_FILE`, `LOG_FILE`, `LOG_FOLDER`, `LOG_ROTATION_ENABLED`, `LOG_MAX_SIZE_MB`, `LOG_BACKUP_COUNT` - Transport: `TRANSPORT_TYPE`, `WEBSOCKET_PING_INTERVAL`, `SSE_RETRY_TIMEOUT` - Tools: `TOOL_TIMEOUT`, `MAX_TOOL_RETRIES`, `TOOL_RATE_LIMIT`, `TOOL_CONCURRENT_LIMIT` --- ## πŸš€ Running & Deployment ???+ example "🏠 How do I run MCP Gateway locally using PyPI?" ```bash python3 -m venv .venv && source .venv/bin/activate pip install mcp-contextforge-gateway mcpgateway ``` ???+ example "🐳 How do I use the provided Makefile and Docker/Podman setup?" ```bash make podman # or make docker make podman-run-ssl # or make docker-run-ssl make podman-run-ssl-host # or make docker-run-ssl-host ``` Docker Compose is also available, ex: `make compose-up`. ???+ example "☁️ How can I deploy MCP Gateway on Google Cloud Run, Code Engine, Kubernetes, AWS, etc?" See the [Deployment Documentation](../deployment/index.md) for detailed deployment instructions across local, docker, podman, compose, AWS, Azure, GCP, IBM Cloud, Helm, Minikube, Kubernetes, OpenShift and more. --- ## πŸ’Ύ Databases & Persistence ???+ info "πŸ—„οΈ What databases are supported for persistence?" - SQLite (default) - used for development / small deployments. - PostgreSQL / MySQL / MariaDB via `DATABASE_URL`. - Redis (optional) for caching and federation. - Other databases supported by SQLAlchemy. ???+ info "πŸ“¦ How do I persist SQLite across container restarts?" Include a persistent volume with your container or Kubernetes deployment. Ex: ```bash docker run -v $(pwd)/data:/app ghcr.io/ibm/mcp-context-forge:1.0.0-RC-1 ``` For production use, we recommend PostgreSQL. A Docker Compose target with PostgreSQL and Redis is provided. --- ## πŸ” Security & Auth ???+ danger "πŸ†“ How do I disable authentication for development?" Set `AUTH_REQUIRED=false` - disables login for local testing. ???+ example "πŸ”‘ How do I generate and use a JWT token?" ```bash export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \ --username admin@example.com --exp 10080 --secret my-test-key) curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools ``` The token is used for all API interactions and can be configured to expire using `-exp`. ???+ tip "πŸ“₯ How do I bulk import multiple tools at once?" Use the `/admin/tools/import` endpoint to import up to 200 tools in a single request: ```bash curl -X POST http://localhost:4444/admin/tools/import \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ --data-binary @tools.json ``` See the [Bulk Import guide](../manage/bulk-import.md) for details on format and error handling. ???+ example "πŸ›‘οΈ How do I enable TLS and configure CORS?" - Use `make podman-run-ssl` for self-signed certs or drop your own certificate under `certs`. - Set `ALLOWED_ORIGINS` or `CORS_ENABLED` for CORS headers. ???+ example "πŸ” How do I pass Authorization headers to upstream MCP servers when the gateway uses authentication?" When MCP Gateway uses authentication (JWT/Bearer/Basic/OAuth), there's a conflict if you need to pass different Authorization headers to upstream MCP servers. **Solution: Use X-Upstream-Authorization header** ```bash # Send X-Upstream-Authorization header - gateway automatically renames it to Authorization for upstream curl -H "Authorization: Bearer $GATEWAY_TOKEN" \ -H "X-Upstream-Authorization: Bearer $UPSTREAM_TOKEN" \ -X POST http://localhost:4444/tools/invoke/my_tool \ -d '{"arguments": {}}' ``` The gateway will: 1. Use the `Authorization` header for gateway authentication 2. Rename `X-Upstream-Authorization` to `Authorization` when forwarding to the upstream MCP server 3. This solves the header conflict and allows different auth tokens for gateway vs upstream --- ## πŸ“‘ Tools, Servers & Federation ???+ example "βž• How do I register a tool with the gateway?" ```bash curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{"name":"clock_tool","url":"http://localhost:9000/rpc","input_schema":{"type":"object"}}' \\ http://localhost:4444/tools ``` ???+ example "πŸŒ‰ How do I add a peer MCP gateway?" A "Gateway" is another MCP Server. The MCP Gateway itself is an MCP Server. This means you can add any MCP Server under "Gateways" and it will retrieve Tools/Resources/Prompts. ```bash curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \\ -d '{"name":"peer","url":"http://peer:4444"}' \\ http://localhost:4444/gateways ``` ???+ example "πŸ–‡οΈ What are virtual servers and how do I use them?" A Virtual Server is a MCP Server composed from Tools/Resources/Prompts from multiple servers. Add one or more MCP Servers under "Gateways", then select which Tools/Prompts/Resources to use to create your Virtual Server. --- ## 🏎️ Performance Tuning & Scaling ???+ example "βš™οΈ What environment variables affect performance?" - `TOOL_CONCURRENT_LIMIT` - `TOOL_RATE_LIMIT` - `WEBSOCKET_PING_INTERVAL` - `SSE_RETRY_TIMEOUT` ???+ example "🧡 How do I scale the number of worker processes?" - Run `mcpgateway --workers 4` (Uvicorn CLI flag) - Set `GUNICORN_WORKERS` when using the bundled Gunicorn scripts ???+ example "πŸ“Š How can I benchmark performance?" Use `hey` against `/rpc` with sample payloads from `tests/hey`. Focus on p99 latency, error rate, and throughput. --- ## πŸ“ˆ Observability & Logging ???+ example "πŸ” How do I enable tracing and observability?" Use OpenTelemetry (OTLP) to export traces to Phoenix, Jaeger, Zipkin, Tempo, DataDog, etc. ```bash export OTEL_ENABLE_OBSERVABILITY=true export OTEL_TRACES_EXPORTER=otlp export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 ``` See the Observability docs for backend-specific setup. Admin UI also shows tool/server/prompt stats. A Prometheus `/metrics` endpoint may be added later. ???+ example "πŸ“œ What log formats are supported?" - `LOG_FORMAT=json` or `text` - Adjust with `LOG_LEVEL` --- ## πŸ§ͺ Smoke Tests & Troubleshooting ???+ example "πŸ›« Is there a full test script I can run?" Yes - see the basic testing guide: [Testing β€Ί Basic](../testing/basic.md). ???+ example "🚨 What common errors should I watch for?" | Symptom | Resolution | |-----------------------|----------------------------------------| | 401 Unauthorized | Refresh token / check Authorization | | database is locked | Use Postgres / increase DB_POOL_SIZE | | already exists errors | Use *Show inactive* toggle in UI | | SSE drops every 30 s | Raise `SSE_RETRY_TIMEOUT` | ???+ example "πŸ”„ What happens if the database or Redis is temporarily unavailable?" The gateway uses **exponential backoff with jitter** for connection retries at startup: - **Retry pattern**: 2s β†’ 4s β†’ 8s β†’ 16s β†’ 30s (capped), with Β±25% random jitter - **Default**: 30 retries β‰ˆ 5 minutes total wait before worker exits - **Benefit**: Prevents CPU-intensive crash-respawn loops during dependency outages Configuration: ```bash DB_MAX_RETRIES=30 # Database retry attempts (default: 30) DB_RETRY_INTERVAL_MS=2000 # Base interval, doubles each attempt REDIS_MAX_RETRIES=30 # Redis retry attempts (default: 30) REDIS_RETRY_INTERVAL_MS=2000 # Base interval, doubles each attempt ``` See [Performance Architecture β€Ί Startup Resilience](../architecture/performance-architecture.md#startup-resilience) for details. --- ## πŸ’» Integration Recipes ???+ example "🦜 How do I use MCP Gateway with LangChain?" ```python import os from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent client = MultiServerMCPClient( { "gateway": { "url": "http://localhost:4444/mcp", "transport": "streamable_http", "headers": {"Authorization": f"Bearer {os.environ['MCPGATEWAY_BEARER_TOKEN']}"} } } ) agent = create_react_agent(tools=client.get_tools(), llm=your_language_model) ``` ???+ example "🦾 How do I connect GitHub's mcp-server-git via Translate Bridge?" ```bash python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9001 ``` --- ## πŸ‘₯ Multi‑Tenancy & Migration (v0.7.0) ???+ example "πŸ” How do I enable email/password login and teams?" Add the following to your `.env`: ```bash EMAIL_AUTH_ENABLED=true PLATFORM_ADMIN_EMAIL=admin@example.com PLATFORM_ADMIN_PASSWORD=changeme AUTO_CREATE_PERSONAL_TEAMS=true ``` Upgrading from earlier releases? Follow [MIGRATION-0.7.0.md](https://github.com/IBM/mcp-context-forge/blob/main/MIGRATION-0.7.0.md). ???+ info "πŸ” Does basic auth still work?" Basic auth for API endpoints is **disabled by default** for security. To enable it, set `API_ALLOW_BASIC_AUTH=true`. Email/password authentication is recommended for the Admin UI. For programmatic API access, use JWT tokens. ???+ info "🧩 How do teams and visibility work?" Users belong to teams. Resources (servers, tools, prompts, resources) can be `private`, `team`, or `public`. Assign via API or Admin UI. Use SSO mappings to auto‑assign teams. --- ## πŸ” SSO & Team Mapping ???+ example "πŸ‘₯ Can I auto‑assign users to teams via SSO?" Yes. Add **Team Mapping** rules to each SSO provider (Admin UI β†’ Manage β†’ SSO β†’ Provider β†’ Team Mapping). Example JSON: ```json { "team_mapping": { "your-org": { "team_id": "team-uuid", "role": "member" } } } ``` You can manage the same payload via the Admin API (`/auth/sso/admin/providers/{id}`) β€” see the SSO guides under Manage β€Ί SSO. --- ## πŸ–§ Stdio Wrapper ???+ example "🧰 How do I use the stdio wrapper with Claude Desktop?" Configure a stdio server in your client: ```json { "mcpServers": { "mcpgateway-wrapper": { "command": "python3", "args": ["-m", "mcpgateway.wrapper"], "env": { "MCP_AUTH": "Bearer ", "MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp", "MCP_TOOL_CALL_TIMEOUT": "120" } } } } ``` See: [mcpgateway.wrapper](../using/mcpgateway-wrapper.md). --- ## 🧾 Protocol Version ???+ info "πŸ“œ Which MCP protocol version is supported?" You can choose the MCP protocol version (e.g., `2025-03-26`) when integrating. See README "Gateway Layer with Protocol Flexibility". ## πŸ—ΊοΈ Roadmap ???+ info "🧭 What features are planned for future versions?" - πŸ” OAuth2 client-credentials upstream auth with full spec compliance - [πŸŒ™ Dark-mode UI](https://github.com/IBM/mcp-context-forge/issues/26) - [🧾 Add "Version and Environment Info" tab to Admin UI](https://github.com/IBM/mcp-context-forge/issues/25) - πŸ”’ Fine-grained role-based access control (RBAC) for Admin UI and API routes and per-virtual-server API keys - πŸ“¦ Marketplace-style tool catalog with categories, tags, and search - πŸ” Support for long-running / async tool executions with polling endpoints - πŸ“‚ UI-driven prompt and resource file management (upload/edit from browser) - πŸ› οΈ Visual "tool builder" UI to design new tools with schema and auth interactively - πŸ§ͺ Auto-validation tests for registered tools (contract + mock invocation) - 🚨 Event subscription framework: trigger hooks or alerts on Gateway changes - 🧡 Real-time tool logs and debug traces in Admin UI - 🧠 Adaptive routing based on tool health, model, or load - πŸ” Filterable tool invocation history with replay support - πŸ“‘ Plugin-based architecture for custom transports or auth methods [Check out the Feature issues](https://github.com/IBM/mcp-context-forge/issues?q=is%3Aissue%20state%3Aopen%20label%3Aenhancement) tagged `enhancement` on GitHub for more upcoming features! --- ## ❓ Rarely Asked Questions (RAQ) ???+ example "πŸ™ Does MCP Gateway work on a Raspberry Pi?" Yes - build as `arm64` and reduce RAM/workers. --- ## 🀝 Contributing & Community ???+ tip "πŸ‘©πŸ’» How can I file issues or contribute?" Use [GitHub Issues](https://github.com/IBM/mcp-context-forge/issues) and [CONTRIBUTING.md](https://github.com/IBM/mcp-context-forge/blob/main/CONTRIBUTING.md). ???+ tip "πŸ§‘πŸŽ“ What code style and CI tools are used?" - Pre-commit: `ruff`, `black`, `mypy`, `isort` - Run `make lint` before PRs ???+ tip "πŸ’¬ Where can I chat or ask questions?" Join the [GitHub Discussions board](https://github.com/IBM/mcp-context-forge/discussions). --- ### πŸ™‹ Need more help? Open an [Issue](https://github.com/IBM/mcp-context-forge/issues) or [discussion](https://github.com/IBM/mcp-context-forge/discussions) on GitHub.