11 KiB
11 KiB
FastMCP CLI Integration Guide
🎯 Overview
The FastMCP servers are integrated into the agentic-flow CLI with commands for starting servers in different transport modes.
📦 Available Commands
# Start stdio MCP server (for Claude Desktop)
npx agentic-flow mcp start
npx agentic-flow mcp stdio
# Start HTTP + SSE server (for web/remote clients)
npx agentic-flow mcp http
npx agentic-flow mcp sse
# Start with custom port
npx agentic-flow mcp http --port 3001
# Start with debug logging
npx agentic-flow mcp stdio --debug
npx agentic-flow mcp http --debug
# List available tools
npx agentic-flow mcp tools
# Show server status
npx agentic-flow mcp status
🚀 Quick Start
1. Install Package
npm install -g agentic-flow
# or
npx agentic-flow
2. Start MCP Server
For Claude Desktop (stdio)
npx agentic-flow mcp start
For Web Apps (HTTP + SSE)
npx agentic-flow mcp http
3. Configure Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"agentic-flow": {
"command": "npx",
"args": ["agentic-flow", "mcp", "start"]
}
}
}
🔧 Implementation
Add to CLI (src/cli.ts)
#!/usr/bin/env node
import { program } from 'commander';
import { spawn } from 'child_process';
import { resolve } from 'path';
program
.name('agentic-flow')
.version('1.0.0')
.description('Agentic Flow CLI with integrated FastMCP servers');
// MCP command group
const mcp = program
.command('mcp')
.description('MCP server commands');
// Start stdio server (default)
mcp
.command('start')
.alias('stdio')
.description('Start stdio MCP server (for Claude Desktop)')
.option('-d, --debug', 'Enable debug logging')
.action((options) => {
console.log('🚀 Starting FastMCP stdio server...');
console.log('📦 Tools: memory_store, memory_retrieve, memory_search, swarm_init, agent_spawn, task_orchestrate\n');
const serverPath = resolve(__dirname, 'mcp/fastmcp/servers/stdio-full.js');
const proc = spawn('node', [serverPath], {
stdio: 'inherit',
env: {
...process.env,
DEBUG: options.debug ? 'fastmcp:*' : undefined
}
});
proc.on('exit', (code) => {
process.exit(code || 0);
});
});
// Start HTTP + SSE server
mcp
.command('http')
.alias('sse')
.description('Start HTTP + SSE server (for web/remote clients)')
.option('-p, --port <port>', 'Port number', '3000')
.option('-d, --debug', 'Enable debug logging')
.action((options) => {
console.log('🚀 Starting FastMCP HTTP + SSE server...');
console.log(`🌐 Port: ${options.port}`);
console.log('📡 SSE endpoint: /events');
console.log('🔧 Tools: 6 (memory × 3, swarm × 3)\n');
const serverPath = resolve(__dirname, 'mcp/fastmcp/servers/http-streaming.js');
const proc = spawn('node', [serverPath], {
stdio: 'inherit',
env: {
...process.env,
PORT: options.port,
DEBUG: options.debug ? 'fastmcp:*' : undefined
}
});
proc.on('exit', (code) => {
process.exit(code || 0);
});
});
// List available tools
mcp
.command('tools')
.description('List available MCP tools')
.action(() => {
console.log('\n📦 Available MCP Tools (6 total)\n');
console.log('Memory Tools:');
console.log(' 1. memory_store - Store values with TTL and namespacing');
console.log(' 2. memory_retrieve - Retrieve stored values');
console.log(' 3. memory_search - Search keys with pattern matching\n');
console.log('Swarm Coordination Tools:');
console.log(' 4. swarm_init - Initialize multi-agent swarms');
console.log(' 5. agent_spawn - Spawn specialized agents');
console.log(' 6. task_orchestrate - Orchestrate distributed tasks\n');
});
// Show server status
mcp
.command('status')
.description('Show MCP server status')
.action(() => {
console.log('\n🔍 FastMCP Server Status\n');
console.log('Available Transports:');
console.log(' ✅ stdio - JSON-RPC over stdio (for local MCP clients)');
console.log(' ✅ HTTP+SSE - HTTP with Server-Sent Events (for web/remote)\n');
console.log('Tools: 6/6 implemented');
console.log(' ✅ memory_store');
console.log(' ✅ memory_retrieve');
console.log(' ✅ memory_search');
console.log(' ✅ swarm_init');
console.log(' ✅ agent_spawn');
console.log(' ✅ task_orchestrate\n');
});
program.parse();
Update package.json
{
"name": "agentic-flow",
"version": "1.0.0",
"bin": {
"agentic-flow": "./dist/cli.js"
},
"scripts": {
"build": "tsc",
"mcp:stdio": "node dist/mcp/fastmcp/servers/stdio-full.js",
"mcp:http": "node dist/mcp/fastmcp/servers/http-streaming.js"
},
"dependencies": {
"commander": "^11.0.0",
"fastmcp": "^0.1.0",
"zod": "^3.22.0"
}
}
📊 Usage Examples
1. Start stdio Server
# Basic usage
npx agentic-flow mcp start
# With debug logging
npx agentic-flow mcp start --debug
# Alternative command
npx agentic-flow mcp stdio
2. Start HTTP Server
# Default port 3000
npx agentic-flow mcp http
# Custom port
npx agentic-flow mcp http --port 8080
# With debug
npx agentic-flow mcp http --debug
3. Check Available Tools
npx agentic-flow mcp tools
Output:
📦 Available MCP Tools (6 total)
Memory Tools:
1. memory_store - Store values with TTL and namespacing
2. memory_retrieve - Retrieve stored values
3. memory_search - Search keys with pattern matching
Swarm Coordination Tools:
4. swarm_init - Initialize multi-agent swarms
5. agent_spawn - Spawn specialized agents
6. task_orchestrate - Orchestrate distributed tasks
4. Check Server Status
npx agentic-flow mcp status
Output:
🔍 FastMCP Server Status
Available Transports:
✅ stdio - JSON-RPC over stdio (for local MCP clients)
✅ HTTP+SSE - HTTP with Server-Sent Events (for web/remote)
Tools: 6/6 implemented
✅ memory_store
✅ memory_retrieve
✅ memory_search
✅ swarm_init
✅ agent_spawn
✅ task_orchestrate
🔌 Integration Scenarios
Claude Desktop
{
"mcpServers": {
"agentic-flow": {
"command": "npx",
"args": ["agentic-flow", "mcp", "start"]
}
}
}
Systemd Service (Linux)
[Unit]
Description=Agentic Flow MCP HTTP Server
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/npx agentic-flow mcp http --port 3000
Restart=always
User=app
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
Docker Compose
version: '3.8'
services:
mcp-server:
image: node:20-alpine
command: npx agentic-flow mcp http --port 3000
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DEBUG=fastmcp:*
restart: unless-stopped
PM2 (Process Manager)
{
"apps": [{
"name": "agentic-flow-mcp",
"script": "npx",
"args": "agentic-flow mcp http --port 3000",
"instances": 1,
"autorestart": true,
"watch": false,
"max_memory_restart": "500M",
"env": {
"NODE_ENV": "production"
}
}]
}
Start with:
pm2 start ecosystem.config.json
pm2 save
pm2 startup
🛠️ Development Workflow
1. Develop
# Edit server code
vim src/mcp/fastmcp/servers/stdio-full.ts
# Build
npm run build
# Test locally
node dist/mcp/fastmcp/servers/stdio-full.js
2. Test via CLI
# Test stdio
npx agentic-flow mcp start --debug
# Test HTTP
npx agentic-flow mcp http --port 3001 --debug
3. Publish
# Build for production
npm run build
# Publish to npm
npm publish
# Users can then use:
npx agentic-flow@latest mcp start
🚀 Advanced Usage
Custom Environment Variables
# Set custom config
export FASTMCP_MAX_CONCURRENT=20
export FASTMCP_TIMEOUT=60000
# Start server
npx agentic-flow mcp http
With PM2 Cluster Mode
{
"apps": [{
"name": "agentic-flow-cluster",
"script": "npx",
"args": "agentic-flow mcp http",
"instances": "max",
"exec_mode": "cluster",
"env": {
"NODE_ENV": "production"
}
}]
}
Behind Nginx Reverse Proxy
server {
listen 80;
server_name mcp.example.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
location /events {
proxy_pass http://localhost:3000/events;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
}
}
📈 Monitoring
Built-in Health Check
# Check if server is running
curl http://localhost:3000/health
# Response:
# {"status":"healthy","timestamp":"2025-10-03T20:00:00.000Z"}
Prometheus Metrics (Future)
// Add to HTTP server
import prometheus from 'prom-client';
const register = new prometheus.Registry();
const toolCalls = new prometheus.Counter({
name: 'mcp_tool_calls_total',
help: 'Total number of MCP tool calls',
labelNames: ['tool', 'status']
});
register.registerMetric(toolCalls);
// In tool execution:
toolCalls.inc({ tool: 'memory_store', status: 'success' });
🔒 Security
Production Deployment
# Use environment-specific config
NODE_ENV=production npx agentic-flow mcp http --port 3000
# Enable rate limiting (future)
RATE_LIMIT_ENABLED=true npx agentic-flow mcp http
# Enable authentication (future)
AUTH_ENABLED=true AUTH_SECRET=xxx npx agentic-flow mcp http
📚 Complete Command Reference
# Main commands
npx agentic-flow mcp start # Start stdio server
npx agentic-flow mcp stdio # Alias for start
npx agentic-flow mcp http # Start HTTP + SSE server
npx agentic-flow mcp sse # Alias for http
npx agentic-flow mcp tools # List available tools
npx agentic-flow mcp status # Show server status
# Options
--port <port> # Set HTTP server port (default: 3000)
--debug # Enable debug logging
--help # Show help
--version # Show version
🎯 Summary
The FastMCP integration provides:
✅ Simple CLI: npx agentic-flow mcp start
✅ Multiple Transports: stdio and HTTP+SSE
✅ 6 Tools: Memory management + Swarm coordination
✅ Production Ready: Systemd, Docker, PM2 support
✅ Easy Integration: Claude Desktop, web apps, scripts
Status: ✅ Ready for Integration Version: 1.0.0 Last Updated: 2025-10-03