Skip to main content

FlowMCP Integration Guide

Learn how to integrate FlowMCP schemas with MCP servers based on official documentation.

Installation

# Install FlowMCP Core
npm install flowmcp-core

Basic Integration

Import FlowMCP

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

MCP Server Setup

FlowMCP integrates with the official MCP SDK:
import { FlowMCP } from './src/index.mjs'
import { Server } from '@modelcontextprotocol/sdk/server/index.js'

// Create MCP server instance
const server = new Server({
    name: 'crypto-api-server',
    version: '1.0.0'
}, {
    capabilities: { tools: {} }
})

// Define your schema
const schema = {
    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: []
        }
    }
}

// Server parameters for authentication
const serverParams = {
    GITHUB_TOKEN: process.env.GITHUB_TOKEN
}

// Activate schema as MCP tools
const { mcpTools } = FlowMCP.activateServerTools({
    server,
    schema,
    serverParams,
    validate: true,
    silent: false
})

console.log('Activated tools:', Object.keys(mcpTools))
// Output: ['github__getUser']

Schema Validation

Always validate schemas before use:
// Validate schema structure
const validation = FlowMCP.validateSchema({ schema })
if (!validation.status) {
    console.error('Schema validation failed:', validation.messages)
    process.exit(1)
}

console.log('✅ Schema validation passed')

Direct API Execution

Execute API calls directly without MCP server:
const userParams = { username: 'octocat' }
const serverParams = { GITHUB_TOKEN: process.env.GITHUB_TOKEN }

const result = await FlowMCP.fetch({ 
    schema, 
    userParams, 
    serverParams, 
    routeName: 'getUser' 
})

if (result.status) {
    console.log('GitHub user:', result.dataAsString)
} else {
    console.error('API request failed:', result.messages)
}

Schema Filtering

Work with multiple schemas using filtering:
const schemas = [schema1, schema2, schema3]

// Filter by namespace and tags
const { filteredArrayOfSchemas } = FlowMCP.filterArrayOfSchemas({
    arrayOfSchemas: schemas,
    includeNamespaces: ['github'],
    excludeNamespaces: [],
    activateTags: [
        'production',        // Include schemas with 'production' tag
        'github.getUser'     // Include only this route
    ]
})

console.log('Filtered schemas:', filteredArrayOfSchemas.length)

Test Generation

Generate and execute tests from schemas:
// Generate test cases
const tests = FlowMCP.getAllTests({ schema })
console.log('Available tests:', tests.length)

// Execute all tests
for (const test of tests) {
    const result = await FlowMCP.fetch({
        schema,
        userParams: test.userParams,
        serverParams: {},
        routeName: test.routeName
    })
    console.log(`${test.routeName}:`, result.status ? '✅' : '❌')
}

Command Line Integration

Parse command line arguments for schema filtering:
// Command line: node server.mjs --includeNamespaces=github --activateTags=production
const config = FlowMCP.getArgvParameters({
    argv: process.argv,
    includeNamespaces: ['default'],
    excludeNamespaces: [],
    activateTags: []
})

console.log('CLI configuration:', config)
// Output: { includeNamespaces: ['github'], activateTags: ['production'], ... }

Error Handling

All FlowMCP methods return structured error responses:
{
    status: boolean,      // Success/failure status
    messages: string[],   // Error messages if any
    dataAsString: string  // Response data (for fetch method)
}
Handle errors consistently:
const result = await FlowMCP.fetch({ schema, userParams, serverParams, routeName })

if (result.status) {
    // Success - process result.dataAsString
    const data = JSON.parse(result.dataAsString)
    console.log('Data:', data)
} else {
    // Failure - handle result.messages
    console.error('Errors:', result.messages)
}

Schema Structure Requirements

Based on the FlowMCP specification, schemas must include:
const schema = {
    // Required fields
    namespace: 'string',      // Letters only, no special characters
    root: 'string',           // Valid HTTPS URL
    routes: {                 // At least one route required
        routeName: {
            requestMethod: 'GET|POST|PUT|DELETE',
            route: 'string',        // API endpoint path
            parameters: [],         // Parameter definitions
            modifiers: []           // Request/response modifiers
        }
    },
    
    // Optional fields
    headers: {},              // Default headers
    tags: [],                 // Schema tags for filtering
    serverParams: {}          // Server-side parameters
}

Best Practices

  1. Validate first: Always use FlowMCP.validateSchema() before using schemas
  2. Handle errors: Check status field in all method responses
  3. Use filtering: Apply FlowMCP.filterArrayOfSchemas() for large schema collections
  4. Test schemas: Generate and run tests with FlowMCP.getAllTests()
  5. Secure credentials: Use environment variables for API keys in serverParams

Resources