maksdizzy/flowapi-mcp-server

FlowAPI MCP Server

Model Context Protocol (MCP) server for integration with FlowAPI system operations.

Overview

This MCP server provides system-level access to FlowAPI endpoints through Claude Code integration, enabling automated operations with sys_key authentication only. The server focuses on read operations and system queries that work reliably with system-level authentication.

Features

• System Authentication: Uses X-SYS-KEY for system-level operations
• Read-Only Focus: Optimized for data retrieval and system queries
• Typed API: Full TypeScript type safety
• Error Handling: Comprehensive error handling and logging
• Reliable Operations: Only includes endpoints verified to work with sys_key auth

Supported Operations

Art & NFT Operations

• list_arts - Get list of arts with filters and pagination
• get_art - Get detailed art information by ID
• get_recommended_arts - Get recommended arts for discovery
• list_art_collections - List art collections with optional filters
• get_art_collection - Get collection details by ID

User Management

• search_users - Search users with filters and pagination
• get_user - Get user information by various IDs (user_id, webapp_user_id, telegram_user_id, discord_user_id, camunda_user_id)
• get_user_wallets - Retrieve user wallet information

Invite System

• get_invited_wallets - Get invited wallet addresses for blockchain integration
• get_invited_wallets_by_token - Get invited wallets for specific token

External Workers & Strategies

• list_external_workers - List external worker configurations
• get_external_worker - Get external worker details
• list_strategies - List available strategies
• get_strategy - Get strategy details

System Information

• health_check - Check API health and status
• get_available_tools - List all available MCP tools

Installation

npm install
npm run build

Configuration

Copy the example configuration:

cp .env.example .env

Edit .env with your FlowAPI configuration:

# FlowAPI Configuration
FLOW_API_URL=https://your-flowapi-instance.com/api
FLOW_API_SYS_KEY=your-system-key-here

# Environment
NODE_ENV=production

# Logging
LOG_LEVEL=info

# MCP Server Configuration
MCP_SERVER_NAME=flowapi-server
MCP_SERVER_VERSION=1.0.0

Usage

Development

npm run dev

Production

npm run build
npm start

Testing

# Test all available endpoints
node dist/test-final.js

Integration with Claude Code

Add to your Claude Code MCP configuration (~/.claude/mcp_servers.json):

{
  "mcpServers": {
    "flowapi": {
      "command": "node",
      "args": ["/path/to/flowapi-mcp-server/dist/index.js"],
      "env": {
        "FLOW_API_URL": "https://your-flowapi-instance.com/api",
        "FLOW_API_SYS_KEY": "your-system-key-here",
        "NODE_ENV": "production"
      }
    }
  }
}

Architecture

Authentication Strategy

This server exclusively uses system key authentication (X-SYS-KEY header) for all operations. JWT-dependent endpoints have been removed to ensure reliability and consistency.

Error Handling

• Comprehensive error responses with detailed information
• HTTP status code preservation
• Structured error messages for debugging

Type Safety

• Full TypeScript implementation
• Zod schema validation for all inputs
• Strict API response typing

API Examples

List Arts with Filters

// Get the first 10 arts
await client.getArts(10, 0, '{"active": true}');

Search Users

// Search for premium users
await client.searchUsers({ 
  is_premium: true, 
  page: 1, 
  page_size: 10 
});

Get User Information

// Get user by different ID types
await client.getUserBy({ user_id: "uuid-here" });
await client.getUserBy({ camunda_user_id: "camunda-id" });
await client.getUserBy({ webapp_user_id: "webapp-uuid" });

Development Notes

Removed Features

The following endpoints were removed due to JWT authentication requirements:

• create_art - Requires user context via JWT
• update_art - Requires user ownership validation
• create_art_collection - Requires user authentication
• get_next_arts - Requires user personalization
• get_arts_history - Requires user context

Adding New Endpoints

1. Add the endpoint method to FlowApiClient
2. Create the tool definition in appropriate tool file
3. Add the handler in the tool's handle function
4. Update type definitions if needed
5. Test with sys_key authentication

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure all tests pass: npm test
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please use the GitHub Issues page.