Skip to main content

​
FlowMCP Schema Specification v1.2.2

The definitive specification for creating valid FlowMCP schemas, based on the official FlowMCP Technical Standard.

​
Schema Structure

Every FlowMCP schema must follow this exact structure from the v1.2.2 specification: 
const schema = {
    // Required fields
    namespace: "exampleNamespace",           // Letters only, no spaces or special chars
    flowMCP: "1.2.2",                      // Exact version string
    root: "https://api.example.com",        // Valid URL, can include server params
    routes: {},                             // Route definitions
    
    // Optional fields  
    name: "Example API",                    // Human-readable name
    description: "Brief explanation of the API",  // Brief explanation
    docs: ["https://example.com/docs"],     // Documentation URLs
    tags: ["production", "exampleapi.getObject"], // Semantic tags
    requiredServerParams: ["API_KEY"],      // Server parameters used
    headers: { Authorization: "Bearer {{API_KEY}}" }, // Default headers
    handlers: {}                            // Custom handler functions
}

​
General Validation Rules

FieldRequirement
namespaceMust be non-empty string; letters only (/^[a-zA-Z]+$/)
flowMCPMust be in "x.x.x" format, e.g. "1.2.2"
rootMust be a valid URL; placeholders like {{API_KEY}} are allowed
requiredServerParamsMust include all placeholders used in root, headers, and parameters.value (excluding {{USER_PARAM}})
tagsFormat: "module.route" or "module.!route" using letters and dots only

​
Route Structure

All routes must declare ALL required fields: 
routes: {
    getExample: {
        requestMethod: "GET",                // Required: GET, POST, PUT, DELETE, PATCH
        description: "Example route",        // Required: Clear description
        route: "/example/:id",               // Required: Route path
        parameters: [],                      // Required: Parameter definitions (can be empty)
        tests: [],                           // Required: Test cases (can be empty)
        modifiers: []                        // Required: Modifiers (can be empty)
    }
}
Critical Rule: All keys (requestMethod, description, route, parameters, tests and modifiers) MUST be declared. If not in use, set to empty array: modifiers: []

​
Parameter Formatting (Single Line)

Each parameter must be written on a single line - this is a strict convention in FlowMCP.

​
✅ Correct Format:

parameters: [
    { position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }
]

​
❌ Incorrect Format:

parameters: [
    {
        position: {
            key: "id", 
            value: "{{USER_PARAM}}",
            location: "insert"
        },
        z: {
            primitive: "string()",
            options: ["length(24)"]
        }
    }
]
Critical Rule: Every parameter using {{USER_PARAM}} must include a valid z object with primitive and options.

​
Position Object

FieldValuesDescription
location”insert”, “query”, “body”, “header”Where parameter goes
keystringParameter name
value"" or ""Parameter source

​
Z Validation Object

​
Available Primitives and Options:

PrimitiveAvailable OptionsExample
string()min(), max(), length(), regex(), email(), url()["length(24)", "regex(/^[a-zA-Z0-9-]+$/)"]
number()min(), max(), int(), positive(), negative()["min(0)", "max(100)", "int()"]
boolean()None[]
array()min(), max(), length()["min(1)", "max(10)"]
object()Custom shape definitions[]

​
Complete Parameter Examples

// Insert parameter (URL path)
{ position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)", "regex(/^[a-zA-Z0-9-]+$/)"] } }

// Query parameter  
{ position: { key: "page", value: "{{USER_PARAM}}", location: "query" }, z: { primitive: "number()", options: ["min(1)", "max(100)", "int()"] } }

// Server parameter (API key in header)
{ position: { key: "Authorization", value: "Bearer {{API_KEY}}", location: "header" }, z: { primitive: "string()", options: ["length(32)"] } }

// Body parameter
{ position: { key: "data", value: "{{USER_PARAM}}", location: "body" }, z: { primitive: "object()", options: [] } }

​
Tags Format

Tags follow the module.route pattern for granular control: 
tags: [
    "production",           // General tag
    "github.getUser",       // Specific route activation  
    "github.!getRepos",     // Route exclusion (with !)
    "crypto"                // Category tag
]

​
Complete Schema Example

export const githubSchema = {
    namespace: "github",
    name: "GitHub API v3", 
    description: "Access GitHub repositories and user data",
    flowMCP: "1.2.2",
    docs: ["https://docs.github.com/en/rest"],
    tags: ["production", "development", "github.getUser"],
    
    root: "https://api.github.com",
    requiredServerParams: ["GITHUB_TOKEN"],
    
    headers: {
        "Accept": "application/vnd.github.v3+json",
        "Authorization": "token {{GITHUB_TOKEN}}",
        "User-Agent": "FlowMCP/1.2.2"
    },
    
    routes: {
        getUser: {
            requestMethod: "GET",
            description: "Get detailed user information",
            route: "/users/{{USER_PARAM}}",
            parameters: [
                { position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)", "regex(/^[a-zA-Z0-9-]+$/)"] } }
            ],
            tests: [
                { name: "Get octocat", userParams: { username: "octocat" }, expectedStatus: 200 }
            ],
            modifiers: []
        }
    },
    
    handlers: {}
}

​
Validation Checklist

Before using a schema, verify: ✅ Namespace contains only letters
✅ flowMCP version is “1.2.2”
✅ Root URL is valid and uses correct parameter types
✅ All routes have ALL required fields (even if empty arrays)
✅ Parameters are single-line format
✅ All have z validation with primitive and options
✅ Server parameters are listed in requiredServerParams
✅ Tags follow module.route format if route-specific

​
Resources