Schema Creation Guide - FlowMCP Documentation

Transform APIs into MCP Tools

FlowMCP schemas are the foundation for creating MCP servers that provide AI applications with access to multiple APIs through standardized tools. Instead of implementing separate MCP servers for each API, you define schemas and FlowMCP handles all the complexity. The Problem: Building MCP servers manually requires deep protocol knowledge, extensive error handling, and individual implementations for each API. FlowMCP Solution: Define each API as a declarative schema, then use activateServerTools() to automatically transform your collection into a fully functional MCP server.

Understanding Schema Architecture

Every FlowMCP schema follows a consistent structure that describes how to interact with a specific API:

import { FlowMCP } from './src/index.mjs'

const basicSchema = {
  // API Identity (required)
  namespace: 'github',           // Letters only, becomes tool prefix
  flowMCP: '1.2.2',
  root: 'https://api.github.com', // Base URL for all requests
  
  // API Endpoints - become MCP tools
  routes: {
    getUser: {                    // Becomes 'github__getUser' MCP tool
      requestMethod: 'GET',
      description: 'Get GitHub user information',
      route: '/users/{{USER_PARAM}}',
      parameters: [
        { position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)"] } }
      ],
      tests: [],
      modifiers: []
    }
  }
}

Schema Transformation: When processed by activateServerTools(), this creates the github_getUser MCP tool that AI applications can invoke directly.

Multi-API MCP Server Implementation

The real power emerges when combining multiple schemas to create comprehensive MCP servers:

// Development Data Schema
const githubSchema = {
  namespace: 'github',
  flowMCP: '1.2.2',
  root: 'https://api.github.com',
  requiredServerParams: ['GITHUB_TOKEN'],
  headers: {
    'Authorization': 'token {{GITHUB_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
  },
  routes: {
    getUser: {
      requestMethod: 'GET',
      description: 'Get GitHub user information',
      route: '/users/{{USER_PARAM}}',
      parameters: [
        { position: { key: "username", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["min(1)", "max(39)"] } }
      ],
      tests: [],
      modifiers: []
    }
  }
}

// Simple demonstration only - single route
const exampleSchema = {
  namespace: 'example',
  flowMCP: '1.2.2',
  root: 'https://api.example.com',
  routes: {
    getObject: {
      requestMethod: 'GET',
      description: 'Get example object',
      route: '/objects/{{USER_PARAM}}',
      parameters: [
        { position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }
      ],
      tests: [],
      modifiers: []
    }
  }
}

// Create MCP Server
const schemas = [githubSchema]

// Transform all schemas into MCP tools
// Result: AI applications now have access to:
// - github__getUser

Impact: FlowMCP transforms schema definitions into fully functional MCP servers with minimal configuration.

Advanced Schema Patterns

Multi-Parameter Route Handling

Real APIs often require complex parameter handling:

const completeSchema = {
  namespace: 'example',
  flowMCP: '1.2.2',
  root: 'https://api.example.com',
  routes: {
    getObject: {
      requestMethod: 'GET',
      description: 'Get object by ID',
      route: '/objects/{{USER_PARAM}}',
      parameters: [
        { position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }
      ],
      tests: [
        { _description: "Test with ID", id: "1234567890abcdef12345678" }
      ],
      modifiers: []
    }
  }
}

Authentication Strategy Patterns

Different APIs use various authentication methods:

// Server parameter example
const serverParamSchema = {
  namespace: 'example',
  flowMCP: '1.2.2',
  root: 'https://api.example.com',
  requiredServerParams: ['API_KEY'],
  headers: {
    'Authorization': 'Bearer {{API_KEY}}'
  },
  routes: {
    getObject: {
      requestMethod: 'GET',
      description: 'Get object by ID',
      route: '/objects/{{USER_PARAM}}',
      parameters: [
        { position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }
      ],
      tests: [],
      modifiers: []
    }
  }
}

Authentication Security: All tokens are managed server-side through environment variables. AI applications never see or handle sensitive credentials.

Schema Validation and Testing

Validation Requirements

FlowMCP enforces strict validation rules: Namespace Requirements:

Must contain only letters (no numbers, hyphens, special characters)
Should be unique within your schema collection
Becomes the prefix for all MCP tool names

Route Structure Requirements:

Must use valid HTTP methods (GET, POST, PUT, DELETE, PATCH)
Parameter placeholders must use {{USER_PARAM}} syntax
Routes are appended to the root URL

Production Schema Testing

Test schemas before deployment:

const validateSchemaCollection = async (schemas) => {
  for (const schema of schemas) {
    // Validate schema structure
    const validation = FlowMCP.validateSchema({ schema })
    
    if (!validation.status) {
      console.error(`❌ ${schema.namespace} validation failed:`, validation.messages)
      return false
    }
    
    console.log(`✅ ${schema.namespace} schema valid`)
    
    // Test API connectivity
    const testResult = await FlowMCP.fetch({
      schema,
      userParams: { USER_PARAM: 'test-value' },
      serverParams: {},
      routeName: Object.keys(schema.routes)[0]
    })
    
    if (testResult.status) {
      console.log(`✅ ${schema.namespace} API connectivity working`)
    } else {
      console.warn(`⚠️  ${schema.namespace} API test failed - check credentials`)
    }
  }
  
  return true
}

// Test all schemas
await validateSchemaCollection([githubSchema])

Building Specialized MCP Servers

Developer-Focused MCP Server

const developmentSchemas = [
  githubSchema
]

// Creates specialized MCP tools for development:
// - github__getUser

Business Intelligence MCP Server

const businessSchemas = [
  exampleSchema
]

Schema Evolution and Maintenance

Version Management Strategy

// Schema versioning for production stability
const exampleSchemaV1 = {
  namespace: 'example',
  flowMCP: '1.2.2',
  root: 'https://api.example.com',
  routes: {
    getObject: {
      requestMethod: 'GET',
      description: 'Get object by ID',
      route: '/objects/{{USER_PARAM}}',
      parameters: [
        { position: { key: "id", value: "{{USER_PARAM}}", location: "insert" }, z: { primitive: "string()", options: ["length(24)"] } }
      ],
      tests: [],
      modifiers: []
    }
  }
}

// Gradual migration strategy
const migrationSchemas = [exampleSchemaV1]

Production Benefits: Schema-based development enables zero-downtime updates, A/B testing of new API integrations, and gradual migration strategies.

Schema Best Practices

Essential Guidelines

Validate Early: Always use FlowMCP.validateSchema() before deployment
Test Connectivity: Verify API endpoints work with real credentials
Namespace Consistency: Use clear, descriptive namespace names
Parameter Validation: Include proper z validation for all parameters
Error Handling: Test error conditions and edge cases

Common Pitfalls

Invalid Namespaces:

// ❌ Wrong
namespace: "github-api"  // No hyphens
namespace: "api2"        // No numbers

// ✅ Correct
namespace: "github"

Missing Parameter Validation:

// ❌ Wrong - no validation
parameters: [
  { position: { key: "q", value: "{{USER_PARAM}}", location: "query" } }
]

// ✅ Correct - includes validation
parameters: [
  { position: { key: "q", value: "{{USER_PARAM}}", location: "query" }, z: { primitive: "string()", options: ["min(1)"] } }
]

Next Steps

Ready to deploy? Continue with the Server Setup Guide to transform your schemas into a working MCP server. Need more schemas? Explore the Schema Library for production-ready examples. Advanced patterns? Study the API Reference for filtering and optimization techniques.

Achievement Unlocked: You now understand how to create FlowMCP schemas that transform any REST API into AI-accessible MCP tools. These schemas serve as the foundation for building sophisticated AI applications with real-world data access.

Getting Started

Development

Reference

​Transform APIs into MCP Tools

​Understanding Schema Architecture

​Multi-API MCP Server Implementation

​Advanced Schema Patterns

​Multi-Parameter Route Handling

​Authentication Strategy Patterns

​Schema Validation and Testing

​Validation Requirements

​Production Schema Testing

​Building Specialized MCP Servers

​Developer-Focused MCP Server

​Business Intelligence MCP Server

​Schema Evolution and Maintenance

​Version Management Strategy

​Schema Best Practices

​Essential Guidelines

​Common Pitfalls

​Next Steps

Transform APIs into MCP Tools

Understanding Schema Architecture

Multi-API MCP Server Implementation

Advanced Schema Patterns

Multi-Parameter Route Handling

Authentication Strategy Patterns

Schema Validation and Testing

Validation Requirements

Production Schema Testing

Building Specialized MCP Servers

Developer-Focused MCP Server

Business Intelligence MCP Server

Schema Evolution and Maintenance

Version Management Strategy

Schema Best Practices

Essential Guidelines

Common Pitfalls

Next Steps