⚒️ MCPForge
Turn Any REST API Into an AI-Ready MCP Server — Automatically, Securely, and Without Boilerplate.
MCPForge transforms existing REST APIs into secure, typed Model Context Protocol
(MCP) servers. It reads OpenAPI 3.x, Swagger 2.0, or a simple developer-friendly
YAML configuration, normalizes it into a strongly typed internal model, generates
predictable MCP tools, and exposes those tools through local stdio or remote
streamable-http transports.
Instead of maintaining handwritten wrappers, duplicating validation schemas, managing authentication separately, and rebuilding transport boilerplate, teams can generate an AI-ready API integration in less than 60 seconds. MCPForge keeps the normalized domain model independent of MCP and HTTP libraries, making the system easier to test, extend, and maintain.
Table of Contents
- The Problem vs. the MCPForge Solution
- Core Features
- System Architecture
- Installation
- 60-Second Quickstart
- CLI Command Reference
- Configuration and Manual API Specs
- Connecting to AI Clients
- Security Model and Guardrails
- Project Directory Structure
- Development and Quality Checks
- Roadmap
- License and Attribution
The Problem vs. the MCPForge Solution
Before MCPForge
AI assistants cannot directly and safely call most REST APIs without a purpose-built MCP integration. Teams traditionally need to:
- Read the API specification manually.
- Write endpoint-specific Python functions.
- Reimplement path, query, header, cookie, and JSON body mapping.
- Maintain duplicate Pydantic request models.
- Generate tool descriptions and names manually.
- Resolve authentication and secret sources safely.
- Implement SSRF and private-network protections.
- Normalize upstream errors for large-language-model recovery.
- Add retries, timeouts, response limits, redirects, and transport lifecycle logic.
- Maintain compatibility as the MCP SDK evolves.
- Rebuild similar boilerplate for every API and endpoint.
One API can become dozens of wrapper modules and still fail to scale as the API changes.
With MCPForge
API specification or manual YAML
|
v
MCPForge ingest
|
v
Normalized API model
|
v
Typed, filtered MCP tools
|
v
stdio or streamable-http server
|
v
Secure AI-to-REST execution
MCPForge separates API parsing from MCP generation and HTTP execution:
OpenAPI / Swagger / Manual YAML
│
▼
Parse + Normalize
│
▼
Filter + Safety Policy
│
▼
Generate MCP Tools
│
▼
Serve through MCP SDK
│
▼
Authenticate + Execute API
The result is a repeatable pipeline:
mcpforge run ./openapi.yaml
That command can import the specification, validate the configuration and security policy, generate deterministic tools, and launch a functioning MCP server with no handwritten endpoint wrappers.
Core Features
Multi-Source API Ingestion
MCPForge accepts multiple API definition formats:
| Source | Supported Formats | Description |
|---|---|---|
| Local file | OpenAPI 3.0 JSON/YAML | Reads a specification from disk |
| Local file | OpenAPI 3.1 JSON/YAML | Supports modern JSON Schema features |
| Local file | Swagger 2.0 JSON/YAML | Converts Swagger operations into the normalized model |
| Remote URL | OpenAPI or Swagger | Downloads and validates a remote specification |
| Manual YAML | mcpforge.yaml |
Describes APIs that lack an official specification |
The ingestion pipeline extracts:
- Base URLs and server definitions
- Paths and HTTP methods
- Operation identifiers
- Summaries and descriptions
- Tags
- Path parameters
- Query parameters
- Header and cookie parameters
- JSON request bodies
- Required and optional fields
- Response schemas
- Deprecated operations
- Operation metadata used by filtering and generation
Decoupled Normalized Domain Model
Every parser emits the same Pydantic v2 model:
ApiDocumentEndpointParameterRequestBodyResponseDefinitionJsonSchemaToolDefinition
Parsers never generate MCP tools directly. The core generator and execution engine only receive normalized domain objects. This architectural boundary allows future protocol adapters for GraphQL, gRPC, SOAP, or internal API registries without rewriting HTTP execution, security, or CLI logic.
OpenAPIParser ─┐
SwaggerParser ─┼──> ApiDocument ──> ToolGenerator
ManualParser ──┘
Deterministic Tool Generation
MCPForge generates clean MCP-compatible tool names, for example:
| REST Operation | Generated Tool |
|---|---|
GET /users/{id} |
get_user |
POST /orders |
create_order |
GET /users/{id}/projects |
get_user_projects |
DELETE /sessions/{id} |
delete_session |
Tool generation provides:
- Deterministic
snake_casenames - Stable collision suffixing
- Operation-ID-aware naming
- Path and HTTP-method fallback naming
- Manual name overrides
- Manual description overrides
- Strict JSON input schemas
- Required/optional field definitions
- Nested request body support
- Parameter-location metadata
- Deprecated endpoint filtering
- Collision and ambiguous-name reporting
Enterprise Security by Default
Safe behavior is the default:
GET,HEAD, andOPTIONSmay be exposed for read operations.POST,PUT, andPATCHrequire explicit write enablement.DELETErequires explicit delete enablement.- Private, loopback, and link-local addresses are blocked.
- DNS resolutions are checked before and where possible during connection.
- Redirect targets are subject to the same network policy.
allowed_hostscan restrict requests to explicit hostnames.- Literal credentials are rejected from project configuration.
- Secrets are resolved only when a request is executed.
- Authorization, API keys, cookies, and static headers are redacted recursively.
Zero-Leak Authentication
MCPForge supports:
- Bearer tokens
- API keys in custom headers
- API keys in query parameters
- HTTP Basic authentication
- Custom static headers
- Environment-variable-only runtime resolution
Credentials are not included in:
- YAML specifications
- Tool descriptions
- MCP schemas
- Terminal logs
- Debug messages
- HTTP exception text
- Structured API errors
- AI-visible tool responses
Resilient Async Execution
The execution engine uses:
- A shared, lifecycle-managed
httpx.AsyncClient - Configurable connect and read timeouts
- Optional transient retry policies
- Exponential backoff
- Configurable maximum attempts
- TLS verification controls
- Redirect handling
- JSON body construction
- Query, path, header, and cookie mapping
- Maximum response payload limits
- Structured HTTP and network errors
Examples of normalized failure categories include:
validation_errorauthentication_failedauthorization_failednot_foundrate_limitedupstream_unavailabletimeoutnetwork_errorinvalid_jsonresponse_too_largehost_blockedretry_exhausted
Dual MCP Transports
MCPForge is designed for both local and remote usage:
- stdio: ideal for Claude Desktop, Cursor, Windsurf, and local VS Code MCP clients
- streamable-http: suitable for remote deployments and centrally managed MCP gateways
The MCP SDK remains isolated behind an adapter layer. The domain model, tool generator, authentication providers, and HTTP execution engine never depend on SDK-specific classes.
System Architecture
┌──────────────────────────────────────────────────────────────────────┐
│ MCPForge Pipeline │
└──────────────────────────────────────────────────────────────────────┘
OpenAPI 3.x ──┐
Swagger 2.0 ──┼──> Source Loaders
Manual YAML ──┘ │
v
┌─────────────────────────────────────────────────────────────────────┐
│ Local / Remote Ingestion + Format Detection + Schema Normalization │
└─────────────────────────────────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────────────┐
│ Unified Pydantic Domain Model │
│ ApiDocument -> Endpoint -> Parameter -> RequestBody -> Responses │
└─────────────────────────────────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────────────┐
│ Filter + Deprecated + Tag + Path + Method + Safety Policies │
└─────────────────────────────────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────────────┐
│ Tool Generation: Naming, Overrides, Collisions, Input JSON Schemas │
└─────────────────────────────────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────────────┐
│ MCP SDK Adapter + Stdio or Streamable HTTP Transport │
└─────────────────────────────────────────────────────────────────────┘
│
v
┌─────────────────────────────────────────────────────────────────────┐
│ Argument Mapping -> Authentication -> SSRF -> HTTP Retry / Limits │
└─────────────────────────────────────────────────────────────────────┘
│
v
Upstream REST API
Module Responsibilities
| Module | Responsibility |
|---|---|
domain |
Pure Pydantic contracts shared by all internal modules |
config |
YAML/JSON loading, merging, validation, and environment references |
ingestion |
Source loading, format detection, parsing, and normalization |
filtering |
Endpoint allowlists, blocklists, tags, methods, and deprecated handling |
generation |
Tool names, descriptions, JSON schemas, and collision resolution |
auth |
Environment-backed authentication providers and credential resolution |
execution |
HTTP request construction, retries, response parsing, and normalized errors |
security |
Operation safety, SSRF protection, host policy, validation, and redaction |
mcp |
MCP SDK adapter and both transport implementations |
runtime |
Dependency composition and shared application lifecycle |
observability |
Redacted structured logging and diagnostics |
cli |
Terminal commands, argument handling, and Rich output |
The dependency direction remains one-way:
cli -> runtime -> generation/filtering/execution
|
v
config -> ingestion -> domain
security -----------------^
mcp ----------------------^
The domain package must not import Typer, Rich, HTTPX, PyYAML, or the MCP SDK.
Installation
Requirements
- Python 3.11 or newer
- An MCP-compatible client for local usage
- Network access to the upstream API, if remote API testing is required
Install with pip
python -m pip install mcpforge
For an isolated environment:
python -m venv .venv
source .venv/bin/activate
python -m pip install mcpforge
mcpforge --help
On Windows:
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install mcpforge
mcpforge --help
Install with uv
uv tool install mcpforge
mcpforge --help
For a project environment:
uv venv
source .venv/bin/activate
uv pip install mcpforge
Install from source
git clone https://github.com/AshishVail/mcpforge.git
cd mcpforge
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
Verify the installation:
mcpforge --version
mcpforge --help
60-Second Quickstart
1. Create a project
mkdir inventory-api && cd inventory-api
mcpforge init
This creates a starter mcpforge.yaml and supporting environment template.
2. Add environment-backed secrets
cp .env.example .env
export MCPFORGE_API_TOKEN="replace-with-your-token"
Never paste a token directly into mcpforge.yaml.
3. Import an API specification
Remote URL:
mcpforge import https://api.example.com/openapi.json
Local file:
mcpforge import ./openapi.yaml
Swagger 2.0:
mcpforge import ./swagger.yaml --format swagger
Manual configuration:
mcpforge import ./mcpforge.yaml --format manual
4. Inspect the generated tools
mcpforge inspect
Example output:
┌───────┬────────────────────────┬───────────────┬──────────────┐
│ Method│ Path │ Tool Name │ Safety │
├───────┼────────────────────────┼───────────────┼──────────────┤
│ GET │ /users/{id} │ get_user │ read │
│ GET │ /users │ list_users │ read │
│ POST │ /orders │ create_order │ write │
└───────┴────────────────────────┴───────────────┴──────────────┘
5. Validate configuration and security
mcpforge validate
The validation pass checks:
- YAML/JSON syntax
- Pydantic configuration models
- Source availability
- Schema validity
- Authentication references
- Write/delete policy
- Deprecated operations
- Host and SSRF policy
- Tool-name collisions
- Required environment variables
6. Test upstream connectivity
mcpforge test
Expected output:
✓ Configuration loaded
✓ Authentication resolved
✓ API host allowed
✓ Connectivity successful
✓ Upstream returned a valid response
7. Start a local MCP server
mcpforge serve --transport stdio
To start the remote HTTP transport:
mcpforge serve --transport streamable-http --host 127.0.0.1 --port 8080
Streamable HTTP endpoint:
http://127.0.0.1:8080/mcp
8. Use the one-command workflow
mcpforge run ./openapi.yaml
With remote OpenAPI:
mcpforge run https://api.example.com/openapi.json --transport stdio
With HTTP transport:
mcpforge run ./openapi.yaml \
--transport streamable-http \
--host 0.0.0.0 \
--port 8080
CLI Command Reference
mcpforge init
Scaffold a new MCPForge project.
mcpforge init
mcpforge init ./my-api
mcpforge init --force
mcpforge init --with-example
| Option | Description |
|---|---|
PATH |
Target project directory |
--force |
Replace existing project files after confirmation |
--with-example |
Include an example OpenAPI and environment file |
--config-name TEXT |
Custom configuration filename |
Creates:
my-api/
├── mcpforge.yaml
├── .env.example
└── examples/
└── petstore.openapi.yaml
mcpforge import
Load and normalize an API specification.
mcpforge import ./openapi.yaml
mcpforge import ./swagger.json --format swagger
mcpforge import https://api.example.com/openapi.json
mcpforge import ./manual.yaml --format manual --save
| Option | Description |
|---|---|
<source> |
Local path or remote URL |
| `--format [openapi | swagger |
--save / --no-save |
Persist normalized project metadata |
--base-url TEXT |
Override a specification's server URL |
--config PATH |
Use a specific project configuration |
mcpforge inspect
Display discovered endpoints and generated tool names.
mcpforge inspect
mcpforge inspect --methods GET
mcpforge inspect --tag users
mcpforge inspect --include-deprecated
mcpforge inspect --format json
| Option | Description |
|---|---|
--methods TEXT |
Filter by comma-separated HTTP methods |
--tag TEXT |
Filter by operation tag |
--path TEXT |
Filter by path substring or pattern |
--include-deprecated |
Include deprecated operations |
| `--format [table | json]` |
mcpforge validate
Validate configuration, specifications, schemas, auth references, and security policy.
mcpforge validate
mcpforge validate --strict
mcpforge validate --config ./config/mcpforge.yaml
mcpforge validate --source ./openapi.yaml
| Option | Description |
|---|---|
--strict |
Treat warnings as validation failures |
--config PATH |
Validate a specific configuration |
--source PATH_OR_URL |
Validate a specific API source |
--show-secrets |
Never available; secret values are intentionally not rendered |
mcpforge test
Verify API connectivity and authentication.
mcpforge test
mcpforge test --operation get_users
mcpforge test --operation get_user --param id=123
mcpforge test --timeout 15
mcpforge test --dry-run
| Option | Description |
|---|---|
--operation TEXT |
Invoke a specific endpoint |
--param KEY=VALUE |
Supply endpoint test parameters |
--timeout FLOAT |
Override HTTP timeout |
--dry-run |
Resolve configuration and auth without sending the request |
--verbose |
Show redacted request diagnostics |
mcpforge serve
Launch the MCP server.
mcpforge serve --transport stdio
mcpforge serve --transport streamable-http --host 127.0.0.1 --port 8080
mcpforge serve --config ./mcpforge.yaml --log-level debug
| Option | Description |
|---|---|
| `--transport [stdio | streamable-http]` |
--host TEXT |
HTTP bind host |
--port INTEGER |
HTTP listen port |
--config PATH |
Project configuration file |
| `--log-level [debug | info |
mcpforge run
Import, validate, generate, and serve in one command.
mcpforge run ./openapi.yaml
mcpforge run https://api.example.com/openapi.yaml --transport stdio
mcpforge run ./openapi.yaml --allow-write
mcpforge run ./openapi.yaml --allow-delete
mcpforge run ./openapi.yaml --transport streamable-http --port 8080
| Option | Description |
|---|---|
<source> |
API specification or manual configuration |
| `--transport [stdio | streamable-http]` |
--host TEXT |
HTTP bind host |
--port INTEGER |
HTTP listen port |
--allow-write |
Explicitly enable write operations |
--allow-delete |
Explicitly enable delete operations |
--include-deprecated |
Include deprecated endpoints |
--config PATH |
Project configuration file |
Global behavior
Every command should fail closed if:
- Authentication secrets are missing.
- Configuration contains literal credentials.
- A source cannot be safely loaded.
- Host policy rules conflict with the source host.
- Write or delete operations are enabled without explicit intent.
- A private or loopback host is discovered.
- The resolved DNS answer is prohibited.
- A tool schema is ambiguous or invalid.
Configuration and Manual API Specs
Complete mcpforge.yaml example
name: inventory-api
source:
location: https://api.example.com/openapi.json
format: openapi
base_url: https://api.example.com
timeout_seconds: 30.0
auth:
type: bearer
token:
env: MCPFORGE_API_TOKEN
required: true
filters:
include_paths:
- /users
- /users/{id}
- /orders
- /orders/{id}
exclude_paths:
- /internal/*
- /admin/*
include_tags:
- Inventory
- Orders
exclude_tags:
- Internal
methods:
- GET
- POST
include_deprecated: false
security:
allow_write_operations: true
allow_delete_operations: false
allowed_hosts:
- api.example.com
block_private_networks: true
max_response_bytes: 5000000
http:
timeout_seconds: 30.0
verify_tls: true
retry:
max_attempts: 3
backoff_seconds: 0.5
Bearer authentication
auth:
type: bearer
token:
env: MCPFORGE_API_TOKEN
required: true
Do not use:
auth:
type: bearer
token: sk-live-hardcoded-secret
API key in a header
auth:
type: api_key
name: X-API-Key
location: header
value:
env: MCPFORGE_API_KEY
required: true
API key in a query parameter
auth:
type: api_key
name: api_key
location: query
value:
env: MCPFORGE_API_KEY
required: true
Basic authentication
auth:
type: basic
username:
env: MCPFORGE_API_USERNAME
required: true
password:
env: MCPFORGE_API_PASSWORD
required: true
Custom static headers
auth:
type: static_headers
headers:
X-Tenant-ID:
env: MCPFORGE_TENANT_ID
required: true
X-Client-Version:
env: MCPFORGE_CLIENT_VERSION
required: false
default: "1.0"
Manual API specification
MCPForge supports manual YAML when no OpenAPI specification is available:
name: Inventory API
version: "1.0.0"
base_url: https://api.example.com
endpoints:
- operation_id: list_products
method: GET
path: /products
summary: List products
description: Returns a paginated product catalog.
tags:
- Inventory
parameters:
- name: limit
location: query
required: false
description: Maximum number of products to return.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
location: query
required: false
schema:
type: string
responses:
- status_code: 200
content_type: application/json
description: Product page
schema:
type: object
properties:
items:
type: array
items:
type: object
next_cursor:
type: string
nullable: true
- operation_id: get_product
method: GET
path: /products/{product_id}
tags:
- Inventory
parameters:
- name: product_id
location: path
required: true
description: Product identifier.
schema:
type: string
responses:
- status_code: 200
content_type: application/json
description: Product found
- status_code: 404
description: Product not found
Manual request bodies use a JSON Schema-like structure:
- operation_id: create_product
method: POST
path: /products
tags:
- Inventory
request_body:
required: true
content_type: application/json
schema:
type: object
required:
- name
- price
properties:
name:
type: string
min_length: 1
price:
type: number
minimum: 0
category:
type: string
enum:
- physical
- digital
Tool override example
tool_overrides:
get_product:
name: fetch_inventory_product
description: Fetch a product by its unique inventory identifier.
delete_product:
enabled: false
Tool overrides must not contain credentials or expose secret values.
Connecting to AI Clients
Set secrets in the environment that launches your MCP client process.
export MCPFORGE_API_TOKEN="your-token"
Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"mcpforge": {
"command": "mcpforge",
"args": [
"serve",
"--transport",
"stdio",
"--config",
"/absolute/path/to/mcpforge.yaml"
],
"env": {
"MCPFORGE_API_TOKEN": "not-recommended-to-place-a-token-here"
}
}
}
}
Prefer resolving secrets through Claude Desktop's environment or a system-level
secret manager. MCPForge can read MCPFORGE_API_TOKEN directly from the process
environment.
Claude Desktop locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux: varies by MCP host configuration
Cursor IDE
Create or update .cursor/mcp.json:
{
"mcpServers": {
"mcpforge": {
"command": "mcpforge",
"args": [
"serve",
"--transport",
"stdio",
"--config",
"${workspaceFolder}/mcpforge.yaml"
],
"env": {
"MCPFORGE_API_TOKEN": "${env:MCPFORGE_API_TOKEN}"
}
}
}
}
VS Code
VS Code MCP configurations commonly use a .vscode/mcp.json file:
{
"servers": {
"mcpforge": {
"type": "stdio",
"command": "mcpforge",
"args": [
"serve",
"--transport",
"stdio",
"--config",
"${workspaceFolder}/mcpforge.yaml"
],
"env": {
"MCPFORGE_API_TOKEN": "${env:MCPFORGE_API_TOKEN}"
}
}
}
}
Use the MCP configuration interface in VS Code if your installed version supports workspace variable substitution or environment expansion.
Windsurf
Add a project or user MCP configuration in the Windsurf MCP settings:
{
"mcpServers": {
"mcpforge": {
"command": "mcpforge",
"args": [
"serve",
"--transport",
"stdio",
"--config",
"/absolute/path/to/mcpforge.yaml"
],
"env": {
"MCPFORGE_API_TOKEN": "${env:MCPFORGE_API_TOKEN}"
}
}
}
}
Use an absolute configuration path if the MCP host process does not inherit the project working directory.
Streamable HTTP Remote Server
Start the server:
MCPFORGE_API_TOKEN="your-token" \
mcpforge serve \
--transport streamable-http \
--host 0.0.0.0 \
--port 8080 \
--config /srv/mcpforge/mcpforge.yaml
Configure a compatible MCP client:
{
"mcpServers": {
"inventory-api": {
"transport": "streamable-http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${MCP_GATEWAY_TOKEN}"
}
}
}
}
Production deployments should place MCPForge behind:
- TLS termination
- Authentication
- Authorization
- Rate limiting
- Restricted network routing
- Health monitoring
- Centralized secret management
Security Model and Guardrails
| Threat or Failure | MCPForge Protection |
|---|---|
| Accidental deletion | DELETE operations remain disabled unless explicitly enabled |
| Accidental writes | POST, PUT, and PATCH remain disabled unless configured |
| SSRF to loopback | Loopback addresses such as 127.0.0.0/8 and ::1 are blocked |
| SSRF to private networks | RFC1918 and equivalent private ranges are blocked by default |
| Link-local access | Link-local IPv4/IPv6 ranges are blocked |
| DNS rebinding | Resolved addresses are checked before execution and redirects |
| Host allowlist bypass | Requests outside allowed_hosts are rejected |
| Literal credentials | Configuration rejects credentials that are not environment references |
| Logs exposing secrets | Recursive redaction removes tokens and authorization values |
| MCP schema leakage | Credentials never become tool arguments or descriptions |
| Context overflow | Maximum response bytes are enforced before AI delivery |
| Invalid upstream JSON | Invalid JSON becomes a structured, recoverable error |
| Token rotation | Secrets resolve at runtime instead of during import or generation |
| Unbounded retries | Retry attempts are capped and backoff is configurable |
| Slow upstream API | Connect and read timeouts prevent indefinite execution |
| Redirect escape | Redirect hosts remain subject to allowed-host and SSRF policy |
| TLS interception | TLS verification is enabled by default |
| Ambiguous tool names | Collision resolution produces deterministic names and warnings |
Operation Safety
Endpoint methods map to coarse safety categories:
| Method | Default Safety |
|---|---|
GET |
Read; enabled by default |
HEAD |
Read; enabled by default |
OPTIONS |
Read; enabled by default |
POST |
Write; explicit opt-in |
PUT |
Write; explicit opt-in |
PATCH |
Write; explicit opt-in |
DELETE |
Delete; explicit opt-in |
A write-enabled project does not imply delete-enabled behavior. Both flags are evaluated independently.
SSRF Defense
Before creating an upstream request, MCPForge should validate:
- The scheme is HTTP or HTTPS.
- The URL host matches
allowed_hosts, where configured. - The hostname can be resolved.
- Every resolved address is outside blocked ranges.
- Redirect targets pass the same checks.
- The selected connection cannot escape the validated address policy.
Private address detection is broad enough to include loopback, private, reserved, link-local, multicast, unspecified, carrier-grade NAT, and other special-purpose address families where applicable.
Secret Redaction
Redaction applies recursively to:
- Dictionaries
- Lists
- Nested error details
- Exception messages
- Header collections
- Query logging
- Diagnostic JSON
- Terminal output
Sensitive names include values associated with:
authorizationcookieset-cookietokenapi_keyapi-keypasswordsecretclient_secretaccess_keysession
Redacted values are replaced consistently rather than being returned to AI clients.
Response Size Protection
Every successful and error response is checked against max_response_bytes.
A payload exceeding the limit should result in:
{
"ok": false,
"error": {
"category": "response_too_large",
"message": "The upstream response exceeded the configured payload limit.",
"status_code": 200,
"retryable": false
}
}
The raw oversized body must not be included in the response delivered to the AI.
Project Directory Structure
mcpforge/
├── pyproject.toml # Build, dependencies, scripts, and tool settings
├── README.md # Project documentation
├── LICENSE # MIT license
├── CHANGELOG.md # Release history
├── Makefile # Common development commands
├── .gitignore # Repository ignore rules
├── .pre-commit-config.yaml # Pre-commit quality hooks
│
├── docs/
│ ├── architecture.md # Architecture and extension points
│ ├── configuration.md # Complete configuration reference
│ ├── security.md # Security guarantees and deployment guidance
│ └── supported-specifications.md
│
├── examples/
│ ├── basic/
│ │ ├── mcpforge.yaml # Basic project configuration
│ │ └── .env.example # Environment variable template
│ └── openapi/
│ └── petstore.yaml # Example OpenAPI specification
│
├── src/
│ └── mcpforge/
│ ├── __init__.py # Package metadata and public exports
│ ├── __main__.py # `python -m mcpforge` entry point
│
│ ├── cli/
│ │ ├── app.py # Typer application
│ │ ├── context.py # Shared CLI context
│ │ ├── output.py # Rich terminal rendering
│ │ └── commands/
│ │ ├── init.py # Project scaffolding
│ │ ├── import_spec.py # API import
│ │ ├── inspect.py # Endpoint and tool inspection
│ │ ├── validate.py # Static validation
│ │ ├── test.py # Connectivity and auth testing
│ │ ├── serve.py # MCP server startup
│ │ └── run.py # One-command pipeline
│
│ ├── config/
│ │ ├── models.py # Pydantic configuration models
│ │ ├── loader.py # YAML/JSON loading
│ │ ├── merger.py # Configuration precedence
│ │ └── secrets.py # Environment-backed secret resolution
│
│ ├── domain/
│ │ ├── enums.py # HTTP, parameter, auth, and safety enums
│ │ ├── models.py # ApiDocument and endpoint contracts
│ │ ├── parameters.py # Parameter helpers
│ │ ├── schemas.py # JSON schema aliases
│ │ └── errors.py # Domain exceptions
│
│ ├── ingestion/
│ │ ├── service.py # Format selection and ingestion workflow
│ │ ├── source.py # Source descriptors
│ │ ├── loaders/ # Local and remote loading
│ │ ├── parsers/ # OpenAPI, Swagger, and manual parsers
│ │ └── normalization/ # Parser-specific conversion helpers
│
│ ├── filtering/
│ │ ├── policies.py # Read/write/delete and deprecation policies
│ │ ├── selectors.py # Path, tag, and method selectors
│ │ └── evaluator.py # Final endpoint inclusion decision
│
│ ├── generation/
│ │ ├── models.py # Generated ToolDefinition contracts
│ │ ├── naming.py # Deterministic snake_case naming
│ │ ├── descriptions.py # Tool descriptions
│ │ ├── collisions.py # Stable collision resolution
│ │ ├── input_schema.py # AI-facing JSON input schemas
│ │ └── service.py # Endpoint-to-tool generation
│
│ ├── auth/
│ │ ├── models.py # Authentication contracts
│ │ ├── providers.py # Bearer, API key, Basic, and static auth
│ │ ├── resolver.py # Runtime auth resolution
│ │ └── redaction.py # Auth-related secret scrubbing
│
│ ├── execution/
│ │ ├── engine.py # Request orchestration
│ │ ├── client.py # Shared AsyncClient lifecycle
│ │ ├── request_builder.py # Path/query/header/body construction
│ │ ├── retry.py # Retry and backoff policy
│ │ ├── response.py # Response parsing
│ │ ├── errors.py # Structured HTTP failures
│ │ └── limits.py # Payload-size enforcement
│
│ ├── security/
│ │ ├── safety.py # Operation safety policy
│ │ ├── ssrf.py # DNS and private-network validation
│ │ ├── hosts.py # Allowed-host enforcement
│ │ ├── validation.py # Cross-cutting security validation
│ │ └── redaction.py # Recursive output/log redaction
│
│ ├── mcp/
│ │ ├── adapter.py # Internal-tool to MCP-SDK adapter
│ │ ├── server.py # MCP server creation
│ │ ├── tools.py # Tool callbacks
│ │ ├── errors.py # MCP-compatible errors
│ │ └── transports.py # stdio and streamable-http
│
│ ├── runtime/
│ │ ├── application.py # Dependency composition
│ │ ├── lifecycle.py # Startup and graceful shutdown
│ │ └── dependencies.py # Runtime dependency providers
│
│ └── observability/
│ ├── logging.py # Redacted logging
│ ├── events.py # Structured events
│ └── diagnostics.py # Safe diagnostics
│
└── tests/
├── conftest.py
├── unit/
│ ├── domain/
│ ├── config/
│ ├── ingestion/
│ ├── filtering/
│ ├── generation/
│ ├── auth/
│ ├── execution/
│ ├── security/
│ ├── mcp/
│ └── runtime/
├── integration/
│ ├── ingestion/
│ ├── execution/
│ └── server/
├── fixtures/
│ ├── openapi/
│ ├── swagger/
│ ├── manual/
│ └── responses/
└── e2e/
Development and Quality Checks
Clone and install
git clone https://github.com/AshishVail/mcpforge.git
cd mcpforge
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
Run unit and integration tests
pytest
With coverage:
pytest --cov=mcpforge --cov-report=term-missing --cov-report=html
Run a focused test directory:
pytest tests/unit/generation
pytest tests/integration/execution
Run Ruff
ruff check .
ruff format --check .
ruff format .
ruff check --fix .
Run mypy
mypy src
Strict typing is recommended for all pull requests.
Makefile targets
make install
make test
make lint
make typecheck
make format
make check
Expected make check sequence:
ruff check .
mypy src
pytest
Pre-commit hooks
python -m pip install pre-commit
pre-commit install
pre-commit run --all-files
Pull request checklist
Before submitting a pull request:
- Changes are covered by focused tests
- Public models remain Pydantic v2-compatible
- Domain code remains framework-independent
- MCP SDK imports stay behind the adapter layer
- Secrets are environment-backed
- Logs and errors pass through redaction
- SSRF and host-policy behavior is preserved
- Write and delete operations remain opt-in
- Ruff and mypy pass
- Documentation reflects CLI behavior or configuration changes
Roadmap
Current Foundation
- Project identity and package structure
- Pydantic normalized domain model
- Strict project configuration
- Environment-variable secret references
- Typer/Rich CLI foundation
- OpenAPI 3.0 and 3.1 ingestion
- Swagger 2.0 conversion
- Manual YAML ingestion
- Deterministic MCP tool generation
- Authentication providers
- SSRF and host protection
- Async HTTP execution
- stdio and streamable-http transports
- Complete CLI workflow
- Enterprise documentation and examples
Near-Term
- OpenAPI specification caching
- Endpoint-level tool overrides
- JSON Schema composition support
- GraphQL or gRPC protocol adapters
- OAuth 2.0 device authorization
- OAuth 2.0 client credentials
- Interactive secret resolution
- Docker and Kubernetes examples
- OpenTelemetry-compatible tracing
- Structured audit events
- Secret-manager provider plugins
- MCP prompt and resource generation
- Response transformation templates
- Interactive local configuration UI
Long-Term
- API registry integration
- Remote specification discovery
- Signed configuration packages
- Policy-as-code plugins
- Organization-wide host allowlists
- Central credential brokers
- Automated schema drift detection
- Built-in API mock server
- Multi-API MCP gateway
- Per-user authorization mapping
- Enterprise audit and observability exports
- Compliance reporting
- Plugin marketplace for parsers and transports
License and Attribution
MCPForge is licensed under the MIT License.
Copyright 2026 AshishVail.
MCPForge is independently maintained and is not affiliated with Anthropic, Claude, Cursor, Microsoft, Windsurf, or the maintainers of the official MCP SDK. All trademarks belong to their respective owners.
If MCPForge helps automate API integration for your team or project, consider:
- Starring the repository
- Reporting bugs and security issues
- Adding supported specifications
- Improving documentation
- Contributing parsers, auth providers, or MCP integrations
- Sharing your deployment architecture
Metadata
Release files for openapi-mcpforge 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openapi_mcpforge-0.1.0.tar.gz | 76.7 kB | Without provenance | Details for openapi_mcpforge-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openapi_mcpforge-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for openapi_mcpforge-0.1.0-py3-none-any.whl |
Total release size: 154.5 kB
Release files / openapi_mcpforge-0.1.0.tar.gz
| Download URL | openapi_mcpforge-0.1.0.tar.gz |
|---|---|
| Size | 76.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c6730db1dd5e477faa17e9e09749bbca33ddb725ce11514e47e7dbf9db84655
|
|
BLAKE2b-256 checksum How to use checksums |
b4eb98b31e0237d766c2de3c689ff13f3eb19c3940f42ba4a176dbdef9423057
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / openapi_mcpforge-0.1.0-py3-none-any.whl
| Download URL | openapi_mcpforge-0.1.0-py3-none-any.whl |
|---|---|
| Size | 77.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f3838ac2680bc9694f1ac3583625fee82802e7815064b5099ced2c20b1fa8375
|
|
BLAKE2b-256 checksum How to use checksums |
b967dfcfdcf49be514ce20b59d4dbbccd984dffd0a010bb0e593276f311c0649
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for openapi-mcpforge 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.