Skip to main content

​
File layout

A generated MCP server contains the following files: 
my-api-server/
├── server.py           # Main MCP server — tool definitions and request handling
├── _models.py          # Pydantic models for parameter and response validation
├── _validators.py      # 50+ format validators (full OAS Format Registry coverage)
├── _auth.py            # Authentication handlers (if API requires authentication)
├── .env                # Credentials and runtime configuration
├── requirements.txt    # Python dependencies
├── LICENSE             # MIT license for generated code
├── Dockerfile          # Production Docker build
├── .mcp.json           # MCP client configuration template
└── README.md           # Setup and usage guide
_auth.py is only generated if the OpenAPI specification defines security schemes. APIs without authentication skip this file entirely.

​
Core files

​
server.py

The main entry point. Contains:
  • Tool definitions — One @mcp.tool() async function per API operation
  • HTTP client setup — Connection pooling, timeouts, mTLS support
  • Resilience logic — Retry with exponential backoff, circuit breaker, rate limiting
  • Authentication injection — Selects correct authentication per operation
  • Response handling — JSON parsing, error formatting, optional validation
  • Transport selection — stdio, SSE, or streamable-http (selected at runtime)
Each tool function follows this flow: 
Validate parameters → Inject authentication → Make HTTP request → Validate response → Return data

​
_models.py

Pydantic models for every operation’s parameters and (optionally) responses. Models are generated from the OpenAPI schema definitions and enforce:
  • Type safety — Correct Python types for each parameter
  • Required fields — Missing required parameters are rejected
  • Format validation — Dates, emails, UUIDs, etc. are validated against their declared formats
  • Strict mode — Unknown fields in requests are rejected (prevents malformed calls)

​
_validators.py

Shared validation infrastructure with 50+ format validators covering all 49 OAS Format Registry formats plus custom extensions:
CategoryFormats
Integerint8, int16, int32, int64, uint8, uint16, uint32, uint64, double-int
Numberfloat, double, decimal, decimal128
Date/timedate-time, date, time, duration, date-time-local, time-local, http-date, unixtime
Identifiersuuid, uri, iri, json-pointer, relative-json-pointer, media-range
Networkipv4, ipv6, hostname, idn-hostname, email, idn-email
Textcommonmark, html, char, regex, password
Structured Fieldssf-integer, sf-decimal, sf-string, sf-token, sf-boolean, sf-binary
Encodingbyte, binary, base64url
Also provides base model classes (StrictModel, PermissiveModel) that all generated models inherit from. See Strict/Permissive models for details.

​
_auth.py

Authentication handler classes, one per security scheme found in your specification. See Authentication for details on each type. Includes OPERATION_AUTH_MAP — a mapping from each operation ID to its required authentication schemes, supporting both OR (use any available) and AND (use all together) logic.

​
Configuration files

​
.env

Runtime configuration split into sections:
.env
# --- Authentication ---
API_KEY=your-api-key
# BEARER_TOKEN=your-token
# OAUTH2_CLIENT_ID=your-client-id
# OAUTH2_CLIENT_SECRET=your-client-secret

# --- API Configuration ---
BASE_URL=https://api.example.com

# --- Timeouts (seconds) ---
HTTPX_CONNECT_TIMEOUT=10.0
HTTPX_READ_TIMEOUT=60.0
HTTPX_WRITE_TIMEOUT=30.0
HTTPX_POOL_TIMEOUT=5.0
TOOL_EXECUTION_TIMEOUT=90.0

# --- Connection Pool ---
CONNECTION_POOL_SIZE=100
MAX_KEEPALIVE_CONNECTIONS=20

# --- Resilience ---
MAX_RETRIES=3
RETRY_BACKOFF_FACTOR=2.0
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT_SECONDS=60
RATE_LIMIT_REQUESTS_PER_SECOND=10

# --- Validation ---
RESPONSE_VALIDATION_MODE=warn

# --- Logging ---
LOG_LEVEL=INFO
LOG_FORMAT=simple
The .env file contains sensitive credentials. Never commit it to version control.

​
requirements.txt

Auto-detected dependencies based on what the generated code imports:
requirements.txt
fastmcp>=2.12.0,<3.0.0
httpx>=0.27.0,<1.0.0
pydantic>=2.0.0,<3.0.0
python-dotenv>=1.0.0,<2.0.0
Additional packages are included when needed:
  • authlib and PyJWT — if OAuth2, OIDC, or JWT authentication is used
  • requests — if OAuth2 browser-based flow is used

​
.mcp.json

Pre-configured MCP client configuration template:
.mcp.json
{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}
Copy this into your MCP client’s configuration file, adjusting the path to server.py.

​
Next steps

Authentication

Configure credentials for each authentication type.

Security features

Circuit breakers, rate limiting, retries.