Skip to main content

⚒️ MCPForge

Turn Any REST API Into an AI-Ready MCP Server — Automatically, Securely, and Without Boilerplate.

Python 3.11+ MCP SDK Compatible Pydantic v2 HTTPX Async License: MIT Code Style: Ruff Type Checked: mypy

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

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:

  • ApiDocument
  • Endpoint
  • Parameter
  • RequestBody
  • ResponseDefinition
  • JsonSchema
  • ToolDefinition

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_case names
  • 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, and OPTIONS may be exposed for read operations.
  • POST, PUT, and PATCH require explicit write enablement.
  • DELETE requires 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_hosts can 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_error
  • authentication_failed
  • authorization_failed
  • not_found
  • rate_limited
  • upstream_unavailable
  • timeout
  • network_error
  • invalid_json
  • response_too_large
  • host_blocked
  • retry_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:

  1. The scheme is HTTP or HTTPS.
  2. The URL host matches allowed_hosts, where configured.
  3. The hostname can be resolved.
  4. Every resolved address is outside blocked ranges.
  5. Redirect targets pass the same checks.
  6. 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:

  • authorization
  • cookie
  • set-cookie
  • token
  • api_key
  • api-key
  • password
  • secret
  • client_secret
  • access_key
  • session

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)

Source distribution for openapi-mcpforge 0.1.0
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)

Table of built distributions (wheels) for openapi-mcpforge 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page