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 readyNo JSON Schema by hand. No transport boilerplate. No config files.
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 |
# Install
pip install mcp-forge
# Scaffold + run
mcp-forge new my-server && cd my-server
mcp-forge run --reloadConnect 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| 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 |
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()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()from mcp_forge.testing import ForgeTestClient
client = ForgeTestClient(app)
def test_add():
result = client.call("add", {"a": 2, "b": 3})
assert result == 5 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
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)
# 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
| 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 |
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- 🐛 Found a bug? → Open an issue
- 💡 Have an idea? → Start a discussion
- 📜 See what's planned → ROADMAP.md
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 | |
benni-inference-engine |
High-Throughput Sovereign Local Inference for 8GB–16GB Consumer GPUs | |
agent-eval-harness |
Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness | |
agent-code-sandbox |
Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents | |
agent-deep-research |
Autonomous Multi-Source Deep Research & Evidence Synthesis Engine | |
agent-browser-mesh |
Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler | |
agent-intent-compiler |
Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents | |
agent-token-optimizer |
Sub-Millisecond Context Compression & Semantic Deduplication Engine | |
bio-sync-operator-os |
Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface | |
agent-cyber-sentinel |
Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction | |
agent-run-ledger |
Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine | |
reality-lock |
Cryptographic State Verification & Invariant Proof Engine for Agents | |
agent-memory-mesh |
Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine | |
benni-operator-gateway |
Human-in-the-Loop Approval & Policy Enforcement Gateway | |
mcp-forge |
Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling | |
benni-nexus |
Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub | |
community-autopilot |
Autonomous GitHub Community Triaging & PR Feedback Agent |
Need autonomous multi-agent swarm orchestration, private datacenter infrastructure, or enterprise governance?
- Official Website: https://benni-os.net
- Operator Mode Playbook: https://benni-os.net/blog/academy.html
- GitHub Organization: https://github.com/Benni-OS
- Maintainer: Benni Alencar
- 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 ⭐


