FieldFlow

FieldFlow turns OpenAPI-described REST endpoints into selectively filtered tools. It generates Pydantic models and FastAPI routes that forward requests to the upstream API and return only the fields the caller asks for. An optional MCP layer exposes those generated OpenAPI tools to Model Context Protocol clients such as Claude Desktop.

Features

• Discovers endpoints and schemas from OpenAPI 3.0 JSON or YAML files.
• Builds request/response Pydantic models dynamically, preserving aliases and optional fields.
• Generates FastAPI routes that accept parameters plus an optional fields list to slice responses.
• Proxies requests with httpx, automatically formatting URL paths and query parameters.
• Works with any OpenAPI-compliant spec, including nested schemas and refs.

What FieldFlow Supports Today

FieldFlow currently has two supported application modes:

1. fieldflow serve-http exposes generated HTTP tool endpoints from an OpenAPI spec.
2. fieldflow-mcp exposes the same generated OpenAPI tools through MCP over stdio.

FieldFlow does not yet wrap arbitrary third-party MCP servers. That direction is planned around MCP tools that expose structured outputSchema, but it is not part of the current release.

Project Layout

fieldflow/
  config.py          # Environment-based settings
  http_app.py        # FastAPI app factory
  openapi_loader.py  # JSON/YAML loader with PyYAML fallback
  proxy.py           # Async HTTP proxy that filters responses to requested fields
  spec_parser.py     # Schema parser and dynamic Pydantic model generator
  tooling.py         # FastAPI router builder for tool endpoints
fieldflow_mcp/
  server.py          # MCP server wrapper built on FastMCP
  cli.py             # CLI entry point for the MCP server
examples/
  jsonplaceholder_openapi.yaml  # Minimal sample spec
  pokeapi_openapi.yaml          # Larger spec for stress-testing

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e '.[mcp]'  # zsh users: quote to avoid globbing
fieldflow serve-http --reload

OpenAPI specs are resolved from FIELD_FLOW_OPENAPI_SPEC_PATH. If the spec includes a servers entry the first URL is used; otherwise set FIELD_FLOW_TARGET_API_BASE_URL.

Environment Variables

Authentication

FieldFlow supports secure API authentication through environment variables. All credentials are handled securely with automatic sanitization in logs and error messages.

Simple Authentication

# Bearer token (OAuth 2.0, JWT)
export FIELDFLOW_AUTH_TYPE=bearer
export FIELDFLOW_AUTH_VALUE=your-token-here

# API Key
export FIELDFLOW_AUTH_TYPE=apikey
export FIELDFLOW_AUTH_HEADER=X-API-Key  # Optional, defaults to X-API-Key
export FIELDFLOW_AUTH_VALUE=your-api-key-here

# Basic authentication
export FIELDFLOW_AUTH_TYPE=basic
export FIELDFLOW_AUTH_VALUE=base64-encoded-credentials

OpenAPI Security Schemes

When your OpenAPI spec defines security schemes, FieldFlow automatically uses them:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

With security schemes, provide credentials using the scheme name:

export FIELDFLOW_AUTH_BEARERAUTH_VALUE=your-bearer-token
export FIELDFLOW_AUTH_APIKEYAUTH_VALUE=your-api-key

Security features:

• Credentials are never logged or stored
• Auth headers are sanitized in all error messages
• Memory-safe handling with immediate credentia

... View full README on GitHub