Schema Format

A FlowMCP schema is a .mjs file with two separate named exports: a static main block and an optional handlers factory function. This separation enables integrity hashing, security scanning, and dependency injection.

This page covers the schema format from the formal specification. See Parameters for parameter details and Security Model for security constraints.

The Two-Export Pattern

// Static, declarative, JSON-serializable — hashable without execution
export const main = {
    namespace: 'provider',
    name: 'SchemaName',
    description: 'What this schema does',
    version: '3.0.0',
    root: 'https://api.provider.com',
    tools: { /* ... */ },
    resources: { /* ... */ },   // optional
    skills: [ /* ... */ ]       // optional
}

Why Two Separate Exports

main can be hashed without calling any function. The runtime reads the static export, serializes it via JSON.stringify(), and computes its hash.
Handlers receive all dependencies through injection. Schema files have zero import statements. The runtime resolves shared lists, loads approved libraries, and passes them into the handlers() factory.
requiredLibraries declares what npm packages the schema needs. The runtime loads them from a security allowlist and injects them.

The `main` Export

All fields in main must be JSON-serializable. No functions, no dynamic values, no imports. Everything must survive a JSON.parse( JSON.stringify( main ) ) roundtrip.

Required Fields

Field	Type	Description
`namespace`	`string`	Provider identifier, lowercase letters only (`/^[a-z]+$/`).
`name`	`string`	Schema name in PascalCase (e.g. `SmartContractExplorer`).
`description`	`string`	What this schema does, 1-2 sentences.
`version`	`string`	Must match `3.\d+.\d+` (semver, major must be `3`).
`root`	`string`	Base URL for all tools. Must start with `https://` (no trailing slash).
`tools`	`object`	Tool definitions. Keys are camelCase tool names. Maximum 8 tools.

Optional Fields

Field	Type	Default	Description
`docs`	`string[]`	`[]`	Documentation URLs for the API provider.
`tags`	`string[]`	`[]`	Categorization tags for tool discovery.
`requiredServerParams`	`string[]`	`[]`	Environment variable names needed at runtime.
`requiredLibraries`	`string[]`	`[]`	npm packages needed by handlers (must be on allowlist).
`headers`	`object`	`{}`	Default HTTP headers applied to all tools.
`sharedLists`	`object[]`	`[]`	Shared list references. See Shared Lists.
`resources`	`object`	`{}`	SQLite-based read-only data resources. See Resources.
`skills`	`array`	`[]`	AI agent skill references. See Skills.

The key routes is accepted as a deprecated alias for tools. Schemas using routes will work in v3.0.0 but will produce warnings in v3.1.0 and errors in v3.2.0. Use flowmcp migrate to update automatically.

Field Details

`namespace`

Only lowercase ASCII letters. No numbers, hyphens, or underscores:

// Valid
namespace: 'etherscan'
namespace: 'coingecko'
namespace: 'defillama'

// Invalid
namespace: 'defi-llama'    // hyphen not allowed
namespace: 'CoinGecko'     // uppercase not allowed

`root`

Must use HTTPS with no trailing slash:

// Valid
root: 'https://api.etherscan.io'
root: 'https://pro-api.coingecko.com/api/v3'

// Invalid
root: 'http://api.etherscan.io'     // must be HTTPS
root: 'https://api.etherscan.io/'   // no trailing slash

`requiredServerParams`

Declares environment variables that must exist at runtime. Values are injected via {{SERVER_PARAM:KEY_NAME}} syntax:

requiredServerParams: [ 'ETHERSCAN_API_KEY' ]

`requiredLibraries`

Declares npm packages that handlers need. Must be on the runtime allowlist (see Security Model):

requiredLibraries: [ 'ethers' ]

Tool Definition

Each key in tools is the tool name in camelCase. The tool name becomes part of the fully qualified name (namespace/schemaFile::tool::toolName).

Tool Fields

Field	Type	Required	Description
`method`	`string`	Yes	HTTP method: `GET`, `POST`, `PUT`, `DELETE`.
`path`	`string`	Yes	URL path appended to `root`. May contain `{{key}}` placeholders.
`description`	`string`	Yes	What this tool does. Appears in tool description.
`parameters`	`array`	Yes	Input parameter definitions. Can be empty `[]`.
`tests`	`array`	Yes	Executable test cases. At least 1 per tool. See Tests.
`output`	`object`	No	Output schema. See Output Schema.
`preload`	`object`	No	Cache configuration. See Preload.

HTTP Methods

Method	Body Allowed	Typical Use
`GET`	No	Read operations, queries
`POST`	Yes	Create operations, complex queries
`PUT`	Yes	Update operations
`DELETE`	No	Delete operations

Path Templates

The path supports {{key}} placeholders that are replaced by insert parameters:

// Static path
path: '/api'

// Single placeholder
path: '/api/v1/{{address}}/transactions'

// Multiple placeholders
path: '/api/v1/{{chainId}}/address/{{address}}/balances'

Every {{key}} placeholder must have a corresponding parameter with location: 'insert'.

The `handlers` Export

The handlers export is a factory function receiving injected dependencies:

export const handlers = ( { sharedLists, libraries } ) => {
    const { ethers } = libraries

    return {
        getContractAbi: {
            preRequest: async ( { struct, payload } ) => {
                const checksummed = ethers.getAddress( payload.address )

                return { struct, payload: { ...payload, address: checksummed } }
            }
        }
    }
}

Injected Dependencies

Parameter	Type	Description
`sharedLists`	`object`	Resolved shared list data, keyed by list name. Deep-frozen (read-only).
`libraries`	`object`	Loaded npm packages from `requiredLibraries`, keyed by package name.

Handler Types

Handler	When	Input	Must Return
`preRequest`	Before the API call	`{ struct, payload }`	`{ struct, payload }`
`postRequest`	After the API call	`{ response, struct, payload }`	`{ response }`

Handler Rules

Handlers are optional. Tools without handlers make direct API calls.
Zero import statements. All dependencies are injected through the factory function.
No restricted globals. fetch, fs, process, eval, Function, setTimeout are forbidden.
sharedLists is read-only. Deep-frozen via Object.freeze(). Mutations throw TypeError.
Handlers must be pure transformations. No side effects, no state mutations, no logging.
Return shape must match. preRequest returns { struct, payload }. postRequest returns { response }.

Runtime Loading Sequence

Naming Conventions

Element	Convention	Pattern	Example
Namespace	Lowercase letters only	`^[a-z]+$`	`etherscan`
Schema name	PascalCase	`^[A-Z][a-zA-Z0-9]*$`	`SmartContractExplorer`
Schema filename	PascalCase `.mjs`	`^[A-Z][a-zA-Z0-9]*\.mjs$`	`SmartContractExplorer.mjs`
Tool name	camelCase	`^[a-z][a-zA-Z0-9]*$`	`getContractAbi`
Parameter key	camelCase	`^[a-z][a-zA-Z0-9]*$`	`contractAddress`
Tag	lowercase with hyphens	`^[a-z][a-z0-9-]*$`	`smart-contracts`

Constraints

Constraint	Value	Rationale
Max tools per schema	8	Keeps schemas focused. Split large APIs into multiple schemas.
Max resources per schema	2	Resources are supplementary data, not primary output.
Max skills per schema	4	Skills compose tools; keep schemas focused.
Version major	`3`	Must match `3.\d+.\d+`.
Namespace pattern	`^[a-z]+$`	Letters only. No numbers, hyphens, or underscores.
Root URL protocol	`https://`	HTTP is not allowed.
Root URL trailing slash	Forbidden	`root` must not end with `/`.
`main` export	JSON-serializable	Must survive `JSON.parse( JSON.stringify() )` roundtrip.
Schema file imports	Zero	All dependencies are injected.

Complete Example

A full Etherscan schema with two tools, one handler, and shared list reference:

export const main = {
    namespace: 'etherscan',
    name: 'SmartContractExplorer',
    description: 'Explore verified smart contracts on EVM-compatible chains via Etherscan APIs',
    version: '3.0.0',
    root: 'https://api.etherscan.io',
    docs: [ 'https://docs.etherscan.io/api-endpoints/contracts' ],
    tags: [ 'smart-contracts', 'evm', 'abi' ],
    requiredServerParams: [ 'ETHERSCAN_API_KEY' ],
    requiredLibraries: [],
    headers: { 'Accept': 'application/json' },
    sharedLists: [
        { ref: 'evmChains', version: '1.0.0', filter: { key: 'etherscanAlias', exists: true } }
    ],
    tools: {
        getContractAbi: {
            method: 'GET',
            path: '/api',
            description: 'Returns the Contract ABI of a verified smart contract',
            parameters: [
                {
                    position: { key: 'module', value: 'contract', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                },
                {
                    position: { key: 'action', value: 'getabi', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                },
                {
                    position: { key: 'address', value: '{{USER_PARAM}}', location: 'query' },
                    z: { primitive: 'string()', options: [ 'min(42)', 'max(42)' ] }
                },
                {
                    position: { key: 'apikey', value: '{{SERVER_PARAM:ETHERSCAN_API_KEY}}', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                }
            ],
            output: {
                mimeType: 'application/json',
                schema: {
                    type: 'object',
                    properties: {
                        status: { type: 'string', description: 'API response status' },
                        message: { type: 'string', description: 'Status message' },
                        result: { type: 'string', description: 'Contract ABI as JSON string' }
                    }
                }
            }
        },
        getSourceCode: {
            method: 'GET',
            path: '/api',
            description: 'Returns the Solidity source code of a verified smart contract',
            parameters: [
                {
                    position: { key: 'module', value: 'contract', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                },
                {
                    position: { key: 'action', value: 'getsourcecode', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                },
                {
                    position: { key: 'address', value: '{{USER_PARAM}}', location: 'query' },
                    z: { primitive: 'string()', options: [ 'min(42)', 'max(42)' ] }
                },
                {
                    position: { key: 'apikey', value: '{{SERVER_PARAM:ETHERSCAN_API_KEY}}', location: 'query' },
                    z: { primitive: 'string()', options: [] }
                }
            ]
        }
    }
}

export const handlers = ( { sharedLists } ) => ({
    getSourceCode: {
        postRequest: async ( { response } ) => {
            const { result } = response
            const [ first ] = result
            const { SourceCode, ABI, ContractName, CompilerVersion, OptimizationUsed } = first

            return {
                response: {
                    contractName: ContractName,
                    compilerVersion: CompilerVersion,
                    optimizationUsed: OptimizationUsed === '1',
                    sourceCode: SourceCode,
                    abi: ABI
                }
            }
        }
    }
})

This example demonstrates: two separate exports, fixed parameters (module, action), user parameters (address), server parameter injection (apikey), a shared list reference, an output schema, and a postRequest handler that flattens the response.

Getting Started

Schemas

Agents

Usage

Specification

The Two-Export Pattern

Why Two Separate Exports

The `main` Export

Required Fields

Optional Fields

Field Details

`namespace`

`root`

`requiredServerParams`

`requiredLibraries`

Tool Definition

Tool Fields

HTTP Methods

Path Templates

The `handlers` Export

Injected Dependencies

Handler Types

Handler Rules

Runtime Loading Sequence

Naming Conventions

Constraints

Complete Example

Getting Started

Schemas

Agents

Usage

Specification

​The Two-Export Pattern

​Why Two Separate Exports

​The main Export

​Required Fields

​Optional Fields

​Field Details

​namespace

​root

​requiredServerParams

​requiredLibraries

​Tool Definition

​Tool Fields

​HTTP Methods

​Path Templates

​The handlers Export

​Injected Dependencies

​Handler Types

​Handler Rules

​Runtime Loading Sequence

​Naming Conventions

​Constraints

​Complete Example

The Two-Export Pattern

Why Two Separate Exports

The `main` Export

Required Fields

Optional Fields

Field Details

`namespace`

`root`

`requiredServerParams`

`requiredLibraries`

Tool Definition

Tool Fields

HTTP Methods

Path Templates

The `handlers` Export

Injected Dependencies

Handler Types

Handler Rules

Runtime Loading Sequence

Naming Conventions

Constraints

Complete Example