# ✨ Features Overview

**ContextForge** is an open source registry and proxy that federates MCP, A2A, and REST/gRPC APIs with centralized governance, discovery, and observability. It provides MCP federation, agent and tool call optimization, rate limiting, auth, caching, plugins, and an HTMX-powered Admin UI.

!!! tip "Gateway URL"
    - Direct installs (`uvx`, pip, or `docker run`): `http://localhost:4444`
    - Docker Compose (nginx proxy): `http://localhost:8080`

---


## 🌐 Multi-Transport Core

???+ abstract "Supported Transports"

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

??? example "Try it: SSE from curl"

    ```bash
    curl -N -H "Accept: text/event-stream" \
         -H "Authorization: Bearer $TOKEN" \
         http://localhost:4444/servers/UUID_OF_SERVER_1/sse
    ```

---


## 🔐 Security

??? tip "Auth mechanisms"

    * **JWT bearer** (default, signed with `JWT_SECRET_KEY`)
    * **Email/password** for the Admin UI (`PLATFORM_ADMIN_EMAIL` / `PLATFORM_ADMIN_PASSWORD`)
    * **HTTP Basic** (optional) for API/docs when `API_ALLOW_BASIC_AUTH=true` or `DOCS_ALLOW_BASIC_AUTH=true`
    * **Custom headers** (e.g., API keys) per tool or gateway

??? info "Rate limiting"

    Set `MAX_TOOL_CALLS_PER_MINUTE` to throttle abusive clients.
    Exceeding the limit returns **HTTP 429** with a `Retry-After` header.

??? example "Generate a 24 h token"

    ```bash
    python3 -m mcpgateway.utils.create_jwt_token \
      --username alice --exp 1440 --secret "$JWT_SECRET_KEY"
    ```

---


## 🛠 Tool & Server Registry

??? success "What you can register"

    | Registry | Entities | Notes |
    |----------|----------|-------|
    | **Tools** | Native MCP tools or wrapped REST / CLI functions | JSON Schema input validation |
    | **Resources** | URIs for blobs, text, images | Optional SSE change notifications |
    | **Prompts** | Jinja2 templates + multimodal content | Versioning & rollback |
    | **Servers** | Virtual collections of tools/prompts/resources | Exposed as full MCP servers |
    | **gRPC Services** | gRPC microservices via automatic reflection | Protocol translation to MCP/JSON |

??? code "REST tool example"

    ```bash
    curl -X POST -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
               "name": "joke_api",
               "url": "https://icanhazdadjoke.com/",
               "requestType": "GET",
               "integrationType": "REST",
               "headers": {"Accept":"application/json"}
             }' \
         http://localhost:4444/tools
    ```

---


## 🧠 LLM Providers & Chat

The **LLM Gateway** unifies multiple AI providers behind a single OpenAI-compatible API surface, and provides
an interactive chat agent that connects LLMs to MCP virtual servers. All LLM features are controlled by the
master flag `LLMCHAT_ENABLED` (default: `true`).

??? info "LLM Architecture"

    The LLM Gateway consists of three surfaces (all loaded under `LLMCHAT_ENABLED=true`):

    1. **Provider registry** — multi-provider configuration with encrypted API keys, health checks, and
       auto-synchronization of available models from upstream providers.
       Supports 12 provider types: OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, Google Vertex, WatsonX,
       Ollama, OpenAI-compatible, Cohere, Mistral, Groq, and Together.

    2. **OpenAI-compatible proxy** — `POST /v1/chat/completions` and `GET /v1/models`,
       a drop-in substitute for the OpenAI API. Routes to the configured provider based on the model ID.
       Returns standard OpenAI chat/completion responses including streaming (SSE).

    3. **Chat agent** — an optional, session-oriented chat layer (`/llmchat/*`) powered by LangChain.
       Connects a selected LLM to one or more MCP virtual servers, creating a ReAct agent that can invoke
       MCP tools during conversation. Features include chat history (Redis-backed), streaming responses,
       thinking/reasoning display, and multi-worker session management.

??? info "LLM Provider Management"

    Providers are configured via the Admin UI (**Settings → LLM Settings**).

    - Add a provider, select the type, enter API keys and
      configuration parameters. API keys are encrypted at rest.
    - Each provider can register multiple models with capability flags (chat, streaming, function calling,
      vision), context windows, and max-output limits.
    - Auto-sync available models from the provider's API with one click.
    - Health checks verify connectivity and credentials.
    - Enable/disable providers and individual models via toggle switches.

??? info "OpenAI-Compatible Proxy"

    The proxy endpoint (`POST /v1/chat/completions`, configurable prefix via `LLM_API_PREFIX`) accepts
    standard OpenAI request bodies and returns Chat Completion or Chat Completion Chunk responses.
    Clients never need provider-specific keys or URLs; the gateway resolves the target provider from the
    database.

    RBAC: requires `llm.invoke` permission for completions, `llm.read` for models endpoint.

??? info "Chat Agent"

    Chat sessions are initialized via `POST /llmchat/connect`: select an MCP virtual server, choose a model,
    and a LangChain ReAct agent is created. Messages sent over `POST /llmchat/chat` are processed with
    MCP tool execution feedback interwoven in the conversation.

    Session state, chat history, and model configuration are stored per-user (Redis-backed in multi-worker
    deployments with automatic cleanup on disconnect).

!!! error "Feature flag"

    All LLM features (proxy, config, admin, chat) are loaded under a single condition: `LLMCHAT_ENABLED=true`.
    Set `LLMCHAT_ENABLED=false` to completely disable all LLM services.

**See also:**
    - [LLM Proxy API](../api/llm-proxy.md) — OpenAI-compatible proxy endpoint documentation
    - [LLM Provider Settings](../manage/llm-settings.md) — Admin UI guide for configuring providers and models
    - [LLM Chat](../using/clients/llm-chat.md) — Interactive chat agent with MCP tool integration

---


## 💰 Cost Control (ToolOps)

??? info "Costs per tool call"

    * Tool-level cost calculation using per-model pricing
    * Prompt & completion token usage tracking
    * Cost breakdown per-called with tool-level and total cost summaries
    * Cost thresholds to prevent runaway spend
    * Per-tool throttling to control expensive operations
    * Historical data for optimization
    * Budget alerts

??? code "Enable ToolOps"

    ```bash
    # Set in your environment or .env file
    TOOLOPS_ENABLED=true
    TOOLOPS_AUTHORIZATION=<token>
    ```

---


## 🔌 gRPC-to-MCP Translation

??? success "Automatic gRPC Integration"

    * **Server Reflection** - Automatically discovers gRPC services and methods
    * **Protocol Translation** - Converts between gRPC/Protobuf ↔ MCP/JSON
    * **Zero Configuration** - No manual schema definition required
    * **TLS Support** - Secure connections to gRPC servers
    * **Metadata Headers** - Custom gRPC metadata for authentication
    * **Admin UI** - Manage gRPC services via web interface

??? code "Register a gRPC service"

    ```bash
    # CLI: Expose gRPC service via HTTP/SSE
    python3 -m mcpgateway.translate --grpc localhost:50051 --port 9000

    # REST API: Register for persistence
    curl -X POST -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
               "name": "payment-service",
               "target": "payments.example.com:50051",
               "reflection_enabled": true,
               "tls_enabled": true
             }' \
         http://localhost:4444/grpc
    ```

??? info "How it works"

    1. Gateway connects to gRPC server using [Server Reflection Protocol](https://grpc.io/docs/guides/reflection/)
    2. Discovers all available services and methods automatically
    3. Translates Protobuf messages to/from JSON
    4. Exposes each gRPC method as an MCP tool
    5. Handles streaming (unary and server-streaming)

??? example "Supported gRPC features"

    | Feature | Status | Notes |
    |---------|--------|-------|
    | Unary RPCs | ✅ Supported | Request-response methods |
    | Server Streaming | ⚠️ Partial | Basic support implemented |
    | Client Streaming | 🚧 Planned | Future enhancement |
    | Bidirectional Streaming | 🚧 Planned | Future enhancement |
    | TLS/mTLS | ✅ Supported | Certificate-based auth |
    | Metadata Headers | ✅ Supported | Custom headers for auth |
    | Reflection | ✅ Required | Auto-discovery mechanism |

---


## 🖥 Admin UI

??? abstract "Built with"

    * **FastAPI** + Jinja2 + HTMX + Alpine.js
    * Tailwind CSS for styling

??? info "📊 Audit & Metadata Tracking"

    * **Comprehensive metadata** for all entities (Tools, Resources, Prompts, Servers, Gateways)
    * **Creation tracking** - who, when, from where, how
    * **Modification history** - change attribution and versioning
    * **Federation source** tracking for MCP server entities
    * **Bulk import** batch identification
    * **Auth-agnostic** - works with/without authentication
    * **Backwards compatible** - legacy entities show graceful fallbacks

---


## 🗄 Persistence, Caching & Observability

??? info "Storage options"

    * **SQLite** (default, development)
    * **PostgreSQL** (recommended for production) - via `DATABASE_URL`

??? example "Redis cache"

    ```env
    CACHE_TYPE=redis
    REDIS_URL=redis://localhost:6379/0
    ```

??? abstract "Observability"

    * Structured JSON logs (tap with `jq`)
    * `/metrics` - Prometheus-friendly counters (`tool_calls_total`, `gateway_up`)
    * `/health` - readiness + dependency checks

---


## 🧩 Dev & Extensibility

??? summary "Highlights"

    * **Makefile targets** - `make dev`, `make test`, `make lint`
    * **400+ unit tests** - Pytest + HTTPX TestClient
    * **VS Code Dev Container** - Python 3.11 + Docker/Podman CLI
    * **Plug-in friendly** - drop-in FastAPI routers or Pydantic models

---


## Next Steps

* **Hands-on Walk-through** → [Quick Start](quick_start.md)
* **Deployment Guides** → [Compose](../deployment/compose.md), [K8s & Cloud](../deployment/index.md)
* **Admin UI deep dive** → [UI Guide](ui.md)

!!! success "Ready to explore"
    With transports, federation, and security handled for you, focus on building great **MCP tools, prompts, and agents**-the gateway
    has your back.
