Skip to content

Commit 92a3f58

Browse files
crivetimihaicrivetimihai
authored
Merge pull request #108 from IBM/mkdocs-updates
Mkdocs updates (quickstart, wrapper)
2 parents f7d8895 + c5658fb commit 92a3f58

File tree

6 files changed

+576
-223
lines changed

6 files changed

+576
-223
lines changed

‎docker-compose.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ services:
2424
# MCP Gateway - the main API server for the MCP stack
2525
# ──────────────────────────────────────────────────────────────────────
2626
gateway:
27-
image: ghcr.io/ibm/mcp-context-forge:latest
27+
image: ghcr.io/ibm/mcp-context-forge:0.1.1
2828
build:
2929
context: .
3030
dockerfile: Containerfile # Same one the Makefile builds

‎docs/docs/index.md

Lines changed: 57 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -9,28 +9,32 @@ owner: Mihai Criveti
99
A flexible FastAPI-based gateway and router for **Model Context Protocol (MCP)** with support for virtual servers. It acts as a unified interface for tools, resources, prompts, virtual servers, and federated gateways — all accessible via rich multi-transport APIs and an interactive web-based Admin UI.
1010

1111
![MCP Gateway](images/mcpgateway.gif)
12+
1213
---
1314

1415
## What it Does
1516

1617
- 🚪 Acts as a **gateway layer** in front of MCP servers or APIs
17-
- 🔗 Connects and federates multiple MCP backends (auto-discovery, failover, merging)
18-
- 🔄 Adapts any REST API into an MCP-compliant tool or server
18+
- 🔗 Connects and federates multiple MCP backends (auto-discovery, fail-over, merging)
19+
- 🔄 Virtualizes REST APIs and external MCP servers as compliant tools and servers
1920
- 🛠️ Centralizes registration and management of tools, prompts, and resources
20-
- 📡 Exposes all endpoints over HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE), and stdio
21+
- 📡 Exposes all endpoints over HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE), and **stdio**
22+
- 📦 Provides a stdio wrapper (`mcpgateway-wrapper`) for terminal-based or headless MCP clients
2123

2224
---
2325

2426
## Key Features
2527

26-
- **Multi-Transport Support**: HTTP, WebSocket, SSE, and stdio support with auto-negotiation
27-
- **Federation & Health Checks**: Auto-discovery, syncing, and monitoring of peer gateways
28-
- **Admin UI**: Visual management of servers, tools, prompts, and resources (HTMX + Tailwind)
29-
- **Tool Wrapping**: Expose REST, CLI, or local functions as JSON-RPC tools
30-
- **Security**: JWT and Basic Auth, rate limits, SSL validation
31-
- **Caching & Observability**: In-memory or Redis/database-backed LRU+TTL caching, structured logs
28+
- **Multi-Transport**: HTTP, WebSocket, SSE, and stdio with auto-negotiation
29+
- **Federation & Health Checks**: Auto-discovery (mDNS or static), syncing, monitoring
30+
- **Admin UI**: Real-time management (HTMX + Tailwind)
31+
- **Tool Wrapping**: REST / CLI / local functions with JSON-Schema validation
32+
- **Security**: JWT + Basic Auth, custom headers, rate limits, SSL control
33+
- **Caching & Observability**: Redis/in-memory/database caching, metrics, structured logs
34+
- **Virtual Servers**: Group tools/resources/prompts into MCP-compliant servers
35+
- **Wrapper Mode**: `mcpgateway-wrapper` turns any remote gateway into a local stdio MCP server
3236

33-
For a list of upcoming features, check out the [ContextForge MCP Gateway Roadmap](architecture/roadmap.md)
37+
For upcoming capabilities, see the [Roadmap](architecture/roadmap.md).
3438

3539
```mermaid
3640
graph TD
@@ -46,7 +50,6 @@ graph TD
4650
Protocol[📡 Protocol - Init Ping Completion]
4751
Federation[🌐 Federation Manager]
4852
Transports[🔀 Transports - HTTP WS SSE Stdio]
49-
5053
Core --> Protocol
5154
Core --> Federation
5255
Core --> Transports
@@ -57,7 +60,6 @@ graph TD
5760
Resources[📁 Resource Service]
5861
Prompts[📝 Prompt Service]
5962
Servers[🧩 Server Service]
60-
6163
Core --> Tools
6264
Core --> Resources
6365
Core --> Prompts
@@ -82,30 +84,59 @@ graph TD
8284

8385
## Audience
8486

85-
MCP Gateway is designed for:
87+
MCP Gateway serves:
8688

87-
- **AI Platform Teams** that want to securely expose a variety of tools and models behind a consistent protocol
88-
- **DevOps Engineers** looking for self-hostable control planes
89-
- **Open-source contributors** building agents, clients, and adapters against MCP
90-
- **Cloud Architects** deploying on Kubernetes, IBM Code Engine, AWS, or Azure
89+
* **AI Platform Teams** building unified gateways for LLM tools & services
90+
* **DevOps Engineers** deploying secure, observable, federated control planes
91+
* **Open-source contributors** extending MCP tooling or adapters
92+
* **Cloud Architects** running on Kubernetes, IBM Code Engine, AWS, Azure, or bare Docker
93+
94+
---
95+
96+
## Installation & Deployment
97+
98+
| Scenario | One-liner / CLI Snippet | Docs |
99+
| ----------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
100+
| **Local (PyPI)** | `pip install mcp-contextforge-gateway && mcpgateway --host 0.0.0.0 --port 4444` | [Quick Start](overview/quick_start.md) |
101+
| **Docker / Podman** | `docker run -p 4444:4444 ghcr.io/ibm/mcp-context-forge:<tag>` | [Containers](deployment/container.md) |
102+
| **Docker-Compose (dev)** | `docker compose up` | [Compose](deployment/compose.md) |
103+
| **Helm / Vanilla Kubernetes** | `helm repo add mcpgw https://IBM.github.io/mcp-context-forge && helm install mcpgw mcpgw/mcpgateway` | [Helm Chart](deployment/helm.md) |
104+
| **Minikube (local k8s)** | `make minikube` | [Minikube Guide](deployment/minikube.md) |
105+
| **OpenShift / OKD** | `oc apply -k openshift/` | [OpenShift](deployment/openshift.md) |
106+
| **Argo CD / GitOps** | `kubectl apply -f argo.yaml` | [Argo CD](deployment/argocd.md) |
107+
| **IBM Cloud – Code Engine** | `ibmcloud ce app create --name mcpgw --image ghcr.io/ibm/mcp-context-forge:<tag>` | [IBM Code Engine](deployment/ibm-code-engine.md) |
108+
| **AWS – ECS (Fargate)** | `aws ecs create-service --cli-input-json file://ecs.json` | [AWS Guide](deployment/aws.md) |
109+
| **AWS – EKS (Helm)** | `helm install mcpgw mcpgw/mcpgateway` | [AWS Guide](deployment/aws.md) |
110+
| **Google Cloud Run** | `gcloud run deploy mcpgw --image ghcr.io/ibm/mcp-context-forge:<tag>` | [GCP Cloud Run](deployment/google-cloud-run.md) |
111+
| **Google GKE (Helm)** | `helm install mcpgw mcpgw/mcpgateway` | [GCP Guide](deployment/google-cloud-run.md) |
112+
| **Azure – Container Apps** | `az containerapp up --name mcpgw --image ghcr.io/ibm/mcp-context-forge:<tag>` | [Azure Guide](deployment/azure.md) |
113+
| **Azure – AKS (Helm)** | `helm install mcpgw mcpgw/mcpgateway` | [Azure Guide](deployment/azure.md) |
114+
115+
116+
> **PyPI Package**: [`mcp-contextforge-gateway`](https://pypi.org/project/mcp-contextforge-gateway/)
117+
118+
> **OCI Image**: [`ghcr.io/ibm/mcp-context-forge:0.1.1`](https://github.com/IBM/mcp-context-forge/pkgs/container/mcp-context-forge)
91119
92120
---
93121

94122
## Get Started
95123

96-
Check out the [Quick Start](overview/index.md) for installation and usage, or go straight to:
124+
Jump straight to:
97125

98-
- [Features Overview](overview/features.md)
99-
- [Admin UI Walkthrough](overview/ui.md)
100-
- [Deployment Options](deployment/index.md)
101-
- [Using the `mcpgateway-wrapper`](using/mcpgateway-wrapper.md)
126+
* [Quick Start Guide](overview/quick_start.md)
127+
* [Features Overview](overview/features.md)
128+
* [Admin UI Walk-through](overview/ui.md)
129+
* [Using the `mcpgateway-wrapper`](using/mcpgateway-wrapper.md)
130+
* [Deployment Options](deployment/index.md)
102131

103132
!!! note
133+
Source → [https://github.com/IBM/mcp-context-forge](https://github.com/IBM/mcp-context-forge)
134+
Docs → [https://ibm.github.io/mcp-context-forge/](https://ibm.github.io/mcp-context-forge/)
104135

105-
The latest version can always be found here: <https://github.com/IBM/mcp-context-forge> and for documentation: <https://ibm.github.io/mcp-context-forge/>
106-
107-
<!-- [Download PDF](pdf/mcpgateway-docs.pdf){ .md-button } [Download DOCX](out/mcpgateway-docs.docx){ .md-button } -->
136+
---
108137

109138
## Authors and Contributors
110139

111-
- Mihai Criveti - IBM Distinguished Engineer, Agentic AI
140+
* **Mihai Criveti** – IBM Distinguished Engineer, Agentic AI
141+
142+
<!-- [Download PDF](pdf/mcpgateway-docs.pdf){ .md-button } [Download DOCX](out/mcpgateway-docs.docx){ .md-button } -->

‎docs/docs/overview/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
nav:
22
- index.md
3+
- quick_start.md
34
- features.md
45
- ui.md
56
- ui-concepts.md

‎docs/docs/overview/features.md

Lines changed: 130 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,168 @@
1-
# Features
1+
# ✨ Features Overview
22

3-
MCP Gateway offers a robust feature set for integrating and managing tools, servers, prompts, and resources under the Model Context Protocol.
3+
MCP Gateway is a **gateway + registry + proxy** purpose-built for the **Model Context Protocol (MCP)**. It unifies REST, MCP, and stdio worlds while
4+
adding auth, caching, federation, and an HTMX-powered Admin UI.
45

5-
---
66

7-
## 🧠 Core Capabilities
7+
---
88

9-
- **Full MCP 2025-03-26 Protocol Support**
10-
Implements all required methods: `initialize`, `ping`, `notify`, `complete`, `createMessage`, and fallback JSON-RPC.
9+
## 🌐 Multi-Transport Core
1110

12-
- **Multi-Transport Support**
13-
Accessible via:
11+
???+ abstract "Supported Transports"
1412

15-
- HTTP/JSON-RPC
16-
- WebSocket (bi-directional with ping/pong)
17-
- Server-Sent Events (SSE)
18-
- stdio (for subprocess embedding)
13+
| Transport | Description | Typical Use-case |
14+
|-----------|-------------|------------------|
15+
| **HTTP / JSON-RPC** | Low-latency request-response, default for most REST clients | Simple tool invocations |
16+
| **WebSocket** | Bi-directional, full-duplex | Streaming chat or incremental tool results |
17+
| **Server-Sent Events (SSE)** | Uni-directional server → client stream | LLM completions or real-time updates |
18+
| **STDIO** | Local process pipes via `mcpgateway-wrapper` | Editor plugins, headless CLI clients |
1919

20-
- **Unified Registry**
21-
Maintains a centralized catalog of:
20+
??? example "Try it: SSE from curl"
2221

23-
- Tools (native or REST-adapted)
24-
- Prompts (Jinja2 templates with schema validation)
25-
- Resources (MIME-aware, URI-addressable)
26-
- Servers (virtual or federated)
27-
- Federated Gateways
22+
```bash
23+
curl -N -H "Accept: text/event-stream" \
24+
-H "Authorization: Bearer $TOKEN" \
25+
http://localhost:4444/servers/1/sse
26+
```
2827

2928
---
3029

31-
## 🌐 Federation & Discovery
30+
## 🌍 Federation & Discovery
31+
32+
??? summary "Features"
33+
34+
* **Auto-discovery** – DNS-SD (`_mcp._tcp.local.`) or static peer list
35+
* **Health checks** – fail-over + removal of unhealthy gateways
36+
* **Capability sync** – merges remote tool catalogs into the local DB
37+
* **Request forwarding** – automatic routing to the correct gateway
38+
39+
??? diagram "Architecture"
40+
41+
```mermaid
42+
graph TD
43+
subgraph Local_Gateway
44+
A[MCP Gateway Core]
45+
end
46+
subgraph Remote_Gateway_1
47+
B[Peer 1]
48+
end
49+
subgraph Remote_Gateway_2
50+
C[Peer 2]
51+
end
52+
A <-- ping / register --> B
53+
A <-- ping / register --> C
54+
```
3255

33-
- Peer discovery (mDNS or explicit list)
34-
- Periodic health checks with failover logic
35-
- Transparent merging of capabilities
36-
- Federation timeouts, retries, and sync intervals configurable
56+
??? note "Configuration"
57+
58+
Enable or tweak discovery via `.env`:
59+
60+
```env
61+
FEDERATION_ENABLED=true
62+
FEDERATION_DISCOVERY=true
63+
FEDERATION_PEERS=https://remote.example.com
64+
HEALTH_CHECK_INTERVAL=30
65+
```
3766

3867
---
3968

40-
## 🛠 Tool Management
69+
## 🔐 Security
70+
71+
??? tip "Auth mechanisms"
72+
73+
* **JWT bearer** (default, signed with `JWT_SECRET_KEY`)
74+
* **HTTP Basic** for the Admin UI
75+
* **Custom headers** (e.g., API keys) per tool or gateway
76+
77+
??? info "Rate limiting"
4178

42-
- Register tools via REST, UI, or JSON-RPC
43-
- Wrap any REST API, CLI command, or function
44-
- Supports:
79+
Set `MAX_TOOL_CALLS_PER_MINUTE` to throttle abusive clients.
80+
Exceeding the limit returns **HTTP 429** with a `Retry-After` header.
4581

46-
- JSON Schema validation
47-
- Concurrency limits
48-
- Rate limiting
49-
- Retry policies
50-
- Output filtering via JSONPath
82+
??? example "Generate a 24 h token"
83+
84+
```bash
85+
python -m mcpgateway.utils.create_jwt_token \
86+
--username alice --exp 1440 --secret "$JWT_SECRET_KEY"
87+
```
5188

5289
---
5390

54-
## 💬 Prompt Templates
91+
## 🛠 Tool & Server Registry
92+
93+
??? success "What you can register"
94+
95+
| Registry | Entities | Notes |
96+
|----------|----------|-------|
97+
| **Tools** | Native MCP tools or wrapped REST / CLI functions | JSON Schema input validation |
98+
| **Resources** | URIs for blobs, text, images | Optional SSE change notifications |
99+
| **Prompts** | Jinja2 templates + multimodal content | Versioning & rollback |
100+
| **Servers** | Virtual collections of tools/prompts/resources | Exposed as full MCP servers |
55101

56-
- Jinja2-powered text blocks
57-
- Enforced schema (required/optional args)
58-
- Versioned templates with rollback
59-
- Used by agents and sampling calls
102+
??? code "REST tool example"
103+
104+
```bash
105+
curl -X POST -H "Authorization: Bearer $TOKEN" \
106+
-H "Content-Type: application/json" \
107+
-d '{
108+
"name": "joke_api",
109+
"url": "https://icanhazdadjoke.com/",
110+
"requestType": "GET",
111+
"integrationType": "REST",
112+
"headers": {"Accept":"application/json"}
113+
}' \
114+
http://localhost:4444/tools
115+
```
60116

61117
---
62118

63-
## 📦 Resource Handling
119+
## 🖥 Admin UI
120+
121+
??? abstract "Built with"
64122

65-
- URI-addressed resources
66-
- MIME type detection
67-
- LRU+TTL caching (in-memory, Redis, or DB)
68-
- SSE-based subscriptions to dynamic resources
123+
* **FastAPI** + Jinja2 + HTMX + Alpine.js
124+
* Tailwind CSS for styling
69125

70126
---
71127

72-
## 📊 Observability
128+
## 🗄 Persistence, Caching & Observability
129+
130+
??? info "Storage options"
73131

74-
- Structured JSON logs
75-
- Log levels per route
76-
- `/health` endpoint with live latency stats
77-
- Metrics for tools, servers, prompts, and gateways
132+
* **SQLite** (default dev)
133+
* **PostgreSQL**, **MySQL/MariaDB**, **MongoDB** — via `DATABASE_URL`
134+
135+
??? example "Redis cache"
136+
137+
```env
138+
CACHE_TYPE=redis
139+
REDIS_URL=redis://localhost:6379/0
140+
```
141+
142+
??? abstract "Observability"
143+
144+
* Structured JSON logs (tap with `jq`)
145+
* `/metrics` – Prometheus-friendly counters (`tool_calls_total`, `gateway_up`)
146+
* `/health` – readiness + dependency checks
78147

79148
---
80149

81-
## 🖥 Admin Interface
150+
## 🧩 Dev & Extensibility
82151

83-
- Interactive UI with full CRUD for:
152+
??? summary "Highlights"
84153

85-
- Tools
86-
- Resources
87-
- Prompts
88-
- Servers
89-
- Gateways
90-
- Roots
91-
- Built with HTMX, Alpine.js, and Tailwind CSS
154+
* **Makefile targets** – `make dev`, `make test`, `make lint`
155+
* **400+ unit tests** – Pytest + HTTPX TestClient
156+
* **VS Code Dev Container** – Python 3.11 + Docker/Podman CLI
157+
* **Plug-in friendly** – drop-in FastAPI routers or Pydantic models
92158

93159
---
94160

95-
## 🔐 Authentication & Security
161+
## Next Steps
162+
163+
* **Hands-on Walk-through** → [Quick Start](quick_start.md)
164+
* **Deployment Guides** → [Compose](../deployment/compose.md), [K8s & Cloud](../deployment/index.md)
165+
* **Admin UI deep dive** → [UI Guide](ui.md)
96166

97-
- Supports both Basic and JWT authentication
98-
- Bearer tokens signed with configurable secrets
99-
- TLS verification options
100-
- Optional anonymous/public mode (`AUTH_REQUIRED=false`)
167+
!!! success "Ready to explore"
168+
With transports, federation, and security handled for you, focus on building great **MCP tools, prompts, and agents**—the gateway has your back.

0 commit comments

Comments
 (0)