Skip to main content
Glama
mcp-forge

mcp-forge

by benni-os

PyPI Tests Python CI License: MIT mypy strict Benni OS Smithery Author

"The FastAPI moment for MCP servers."

⭐ What Is mcp-forge?

mcp-forge eliminates MCP server boilerplate entirely. You write a typed Python function. The framework derives the JSON Schema from your type hints, validates inputs at runtime, and exposes the tool over STDIO, HTTP, or SSE — without changing a single line of your logic.

Every MCP server starts the same way: hand-craft JSON Schema, wire a transport loop, handle notifications/initialized, redirect stderr, copy-paste validation logic. mcp-forge does all of that for you.

from mcp_forge import Forge

app = Forge(name="my-server", version="1.0.0")


@app.tool(description="Search the knowledge base")
async def search(query: str, limit: int = 10) -> list[dict]:
    """Returns ranked results for the given query."""
    ...  # your logic here


if __name__ == "__main__":
    app.run()  # STDIO — Claude Desktop / Cursor / VS Code ready

No JSON Schema by hand. No transport boilerplate. No config files.

Related MCP server: Berry MCP Server

⚡ Core Doctrine

These are not features. These are design laws.

☔ Principle

🔧 Implementation

Schema is Derived, Never Written

Pydantic v2 generates full draft-07 JSON Schema from type hints — automatically

Transport is a Runtime Concern

STDIO · HTTP · SSE — switch with one flag, tool code never changes

Contrib is Opt-In

app.include(memory) adds tools; you stay in control, zero forced dependencies

Strict by Default

mypy strict + ruff + 100% typed public API — no surprises in production

Testing Without a Server

ForgeTestClient calls tools directly — no sockets, no mocking, no overhead

Zero Boilerplate

@app.tool() is the entire registration API — one decorator, full MCP compliance

🚀 Quick Start

# Install
pip install mcp-forge

# Scaffold + run
mcp-forge new my-server && cd my-server
mcp-forge run --reload

Connect to Claude Desktop in 30 seconds:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["-m", "my_server"]
    }
  }
}

Switch to HTTP transport with one flag:

mcp-forge run --transport http --port 8080

✨ Features

Feature

Description

🏗️ Declarative Tools

@app.tool() — no schema files, no registration calls

🧠 Auto JSON Schema

Pydantic v2 under the hood — full draft-07 generated from type hints

✅ Runtime Validation

Inputs validated before execution — errors as proper MCP-spec responses

🚀 Multi-Transport

STDIO · HTTP · SSE — switch at runtime, logic unchanged

⏳ Async-First

async def and def tools work side by side — no event loop management

🔌 Contrib Routers

memory · filesystem · web — one-line include

🧪 Testing Client

ForgeTestClient — no server, no mocking, no sockets

📦 PEP 561 Typed

Ships py.typed — full mypy strict + Pyright support

📚 Examples

Minimal server

from mcp_forge import Forge

app = Forge(name="calculator")


@app.tool()
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b


app.run()

With contrib tools

from mcp_forge import Forge
from mcp_forge.contrib import memory, filesystem, web

app = Forge(name="agent-tools")
app.include(memory)  # remember(), recall(), forget(), list_memory()
app.include(filesystem)  # read_file(), write_file(), list_dir(), delete_file()
app.include(web)  # fetch_url()

app.run()

Unit testing — no server needed

from mcp_forge.testing import ForgeTestClient

client = ForgeTestClient(app)


def test_add():
    result = client.call("add", {"a": 2, "b": 3})
    assert result == 5

🏗️ Architecture

  Claude Desktop / Cursor / VS Code / Custom LLM Agents
         │
         ├──► STDIO JSON-RPC 2.0 (mcp-forge run)
         └──► HTTP / SSE Transport (mcp-forge run --transport http|sse)
                       │
                       ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                              mcp-forge                              │
  │                                                                     │
  │  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐  │
  │  │ Declarative @tool │  │  Pydantic v2      │  │ Runtime         │  │
  │  │ Registry          │─►│  Auto-Schema      │─►│ Validator       │  │
  │  │ • Sync & Async    │  │  • Draft-07 JSON  │  │ • Input Guard   │  │
  │  │ • Contrib Routers │  │  • Type Coercion  │  │ • Output Guard  │  │
  │  └───────────────────┘  └───────────────────┘  └─────────────────┘  │
  │                                                                     │
  │  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐  │
  │  │ Transport Layer   │  │  In-Process       │  │ Live Telemetry  │  │
  │  │ • STDIO / HTTP    │  │  ForgeTestClient  │  │ & Doctor /      │  │
  │  │ • SSE Streaming   │  │  • Zero-Socket    │  │ Bench Matrix    │  │
  │  └───────────────────┘  └───────────────────┘  └─────────────────┘  │
  └─────────────────────────────────────────────────────────────────────┘
         │                                         │
         ▼                                         ▼
   Typed Tool Execution                      MCP Spec 2024-11-05
   (memory / filesystem / web)               Structured Responses

📁 Project Structure

mcp-forge/
├── mcp_forge/
│   ├── __init__.py                   # Public Forge, ForgeConfig & exception exports
│   ├── py.typed                      # PEP 561 strict typing marker
│   ├── core/
│   │   ├── config.py                 # ForgeConfig dataclass
│   │   ├── exceptions.py             # MCP-aligned exception hierarchy
│   │   ├── forge.py                  # Declarative Forge app & @app.tool() registry
│   │   ├── schema.py                 # Auto JSON Schema (draft-07) from Pydantic v2
│   │   └── validator.py              # Runtime input/output validation engine
│   ├── serve/
│   │   ├── __init__.py               # Serving & telemetry subpackage exports
│   │   └── telemetry.py              # P50/P90/P99 latency & tool call metrics
│   ├── tools/
│   │   ├── __init__.py               # Diagnostics & benchmark subpackage exports
│   │   ├── bench_matrix.py           # Multi-batch tool dispatch benchmark matrix
│   │   └── doctor.py                 # Runtime dependency & schema probe
│   ├── transports/
│   │   ├── __init__.py               # Transport exports
│   │   ├── http.py                   # FastAPI-based HTTP REST transport
│   │   ├── sse.py                    # Server-Sent Events streaming transport
│   │   └── stdio.py                  # STDIO JSON-RPC 2.0 transport
│   ├── cli/
│   │   ├── main.py                   # Typer CLI (new, run, validate, build)
│   │   └── validator.py              # CLI schema & manifest validator
│   ├── contrib/
│   │   ├── __init__.py               # Opt-in contrib router exports
│   │   ├── filesystem.py             # Sandboxed filesystem tools
│   │   ├── memory.py                 # Scoped in-process memory store
│   │   └── web.py                    # Resilient HTTP fetch tool
│   └── testing/
│       ├── __init__.py               # Testing client exports
│       └── client.py                 # Zero-socket in-process ForgeTestClient
├── docs/
│   └── ARCHITECTURE.md               # Framework & subpackage architecture spec
├── examples/
│   ├── contrib_router_demo.py        # Contrib memory router + TelemetryEngine demo
│   └── quickstart_server.py          # Minimal Forge app + ForgeTestClient example
├── scripts/
│   ├── benchmark_dispatch.py         # Tool dispatch throughput benchmark runner
│   └── gate_schema_validation.py     # Pydantic v2 strict validation gate script
└── tests/                            # Full pytest suite (29 tests)

📦 Installation

# Core only (STDIO transport)
pip install mcp-forge

# With HTTP + SSE transports
pip install "mcp-forge[http]"

# Everything
pip install "mcp-forge[all]"

Requires: Python 3.11+ · pydantic>=2.0

🌍 Ecosystem Compatibility

Client

Transport

Status

Claude Desktop

STDIO

✅ Tested

Cursor

STDIO

✅ Tested

VS Code (GitHub Copilot)

STDIO · HTTP

✅ Tested

Continue.dev

HTTP · SSE

✅ Tested

Custom LLM agents

HTTP · SSE

✅ Tested

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the full guide.

git clone https://github.com/benni-os/mcp-forge
cd mcp-forge
pip install -e ".[dev]"
pytest

🌐 The Benni OS Open-Source Ecosystem

mcp-forge is part of the coordinated Benni Master OS v9.4 open-source infrastructure suite:

Repository

Focus & Architecture

Stars

conductor-sdd

Zero-Dependency Spec-Driven Development, Static AST Drift Detector & MCP Guardrail

GitHub Stars

benni-inference-engine

High-Throughput Sovereign Local Inference for 8GB–16GB Consumer GPUs

GitHub Stars

agent-eval-harness

Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness

GitHub Stars

agent-code-sandbox

Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents

GitHub Stars

agent-deep-research

Autonomous Multi-Source Deep Research & Evidence Synthesis Engine

GitHub Stars

agent-browser-mesh

Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler

GitHub Stars

agent-intent-compiler

Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents

GitHub Stars

agent-token-optimizer

Sub-Millisecond Context Compression & Semantic Deduplication Engine

GitHub Stars

bio-sync-operator-os

Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface

GitHub Stars

agent-cyber-sentinel

Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction

GitHub Stars

agent-run-ledger

Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine

GitHub Stars

reality-lock

Cryptographic State Verification & Invariant Proof Engine for Agents

GitHub Stars

agent-memory-mesh

Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine

GitHub Stars

benni-operator-gateway

Human-in-the-Loop Approval & Policy Enforcement Gateway

GitHub Stars

mcp-forge

Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling

GitHub Stars

benni-nexus

Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub

GitHub Stars

community-autopilot

Autonomous GitHub Community Triaging & PR Feedback Agent

GitHub Stars


🏛️ Commercial & Sovereign Architecture

Need autonomous multi-agent swarm orchestration, private datacenter infrastructure, or enterprise governance?


📄 License & Provenance

  • License: MIT License

  • Author: Benni Alencar (bennialencar@benni-os.net)

  • Architecture: Benni Master OS v9.4 Tier-0 Governance Standard

mcp-forge — Open-Source Python MCP Framework by Benni OS • benni-os.net • MIT License

ZERO_BOILERPLATE • AUTO_SCHEMA • MULTI_TRANSPORT • STRICT_TYPING • MIT_LICENSE

Engineered by Benni Alencar and the Benni OS Core Engineering Group · If mcp-forge saves you time, give it a ⭐

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A universal framework for creating and deploying custom Model Context Protocol (MCP) tool servers with decorator-based tool registration, supporting multiple transports and automatic JSON schema generation for AI assistants.
      2
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A Python library to build MCP servers with decorators, auto-generating JSON Schema from type hints and including built-in filesystem and HTTP servers.
      3
      MIT