Skip to main content

​
The Problem

AI agents need tools organized by domain — “get crypto prices”, “check weather”, “fetch GitHub repos”. But APIs are organized by provider — each with different authentication, URL structures, rate limits, and response formats. Integrating each API manually means writing custom server code, parameter validation, error handling, and response formatting — per provider. At 5 APIs this is tedious. At 50 it is unmaintainable. At 187+ it is impossible without a systematic approach. The core tension: AI clients are non-deterministic (they decide which tool to call), but the tools themselves must be deterministic (they must guarantee correct behavior). Bridging this gap for hundreds of APIs requires a normalization layer.

​
The Solution

FlowMCP is a schema-driven normalization layer between web data sources and AI clients. Each schema is a .mjs file that declares:
  • Inputs — what parameters the tool accepts (with Zod validation)
  • URL construction — how parameters map to API endpoints
  • Authentication — which server-side credentials are required
  • Response transformation — optional handlers that reshape API responses
  • Output schema — what the AI client can expect back
  • Security constraints — which libraries (if any) the schema may use
The FlowMCP runtime reads these schemas and exposes them as MCP tools. No custom server code required.

​
The Key Insight

FlowMCP v2.0.0 separates each schema into two exports:
ExportPurposeProperties
mainDeclarative configurationJSON-serializable, hashable, describes endpoints
handlersExecutable logicFactory function, receives injected dependencies, transforms responses
This separation enables:
  • Integrity hashing — the main export can be hashed to detect tampering
  • Security scanning — handlers can be statically analyzed before execution
  • Shared list injection — reusable value lists are injected at load-time, not imported
  • Output schemas — each route can declare its response structure for AI clients
Most schemas only need the main export. The handlers export is optional and only needed when API responses require transformation before being returned to the AI client.

​
Design Principles

FlowMCP follows five design principles that shape every architectural decision:
Given the same schema and parameters, FlowMCP always produces the same API call. No magic, no inference, no hidden behavior. What the schema declares is exactly what happens.
Schemas describe what an API endpoint looks like — not how to call it. URL construction, parameter validation, and header injection are handled by the runtime based on declarations.
Schemas cannot import modules freely. Required libraries and shared lists are injected by the runtime through controlled interfaces. This prevents supply chain attacks and ensures reproducibility.
The main export is JSON-serializable by design. This means it can be hashed, compared, and verified. Schema integrity is provable, not assumed.
By default, schemas can do nothing beyond declaring API endpoints. Capabilities like library access or response transformation must be explicitly declared and are checked at load-time.

​
Where FlowMCP Sits

FlowMCP occupies the deterministic middle layer between non-deterministic AI clients and uncontrolled external data sources:
LayerBehaviorRole
AI Client (Claude, GPT, etc.)Non-deterministicDecides which tool to call based on context
FlowMCPDeterministicGuarantees how each tool behaves via schemas
Web Data Sources (APIs)External, uncontrolledProvide raw data with varying formats and auth
The AI client chooses the tool. FlowMCP guarantees the tool works correctly. The API provides the data.

​
What’s New in v2.0.0

  • Two-export pattern — main (declarative) + handlers (executable) replaces the single-object schema
  • Output schemas — routes can declare response structure for AI client consumption
  • Shared lists — reusable value enumerations injected at load-time (e.g., chain IDs, token symbols)
  • Security model — zero imports in schemas, library allowlist, static analysis at load
  • Route-level tests — built-in test declarations per route for validation
  • Preload support — schemas can declare data to fetch before tool execution
  • Group prompts — schema groups can include AI-facing prompt context
  • 79 validation rules — comprehensive schema validation covering structure, security, and correctness
For the complete technical specification, see the Specification v2.0.0 section.