How to Integrate Ruflo with Other Tools Using the Model Context Protocol

You can integrate Ruflo with any MCP-compatible client by starting the MCP server via npx ruflo@latest mcp start and configuring your client to connect via stdio, HTTP, or WebSocket transport.

The ruvnet/ruflo repository provides a multi-agent orchestration framework that exposes swarm coordination, agent lifecycle management, and memory services through a standardized Model Context Protocol (MCP) server. When you integrate Ruflo with other tools, you leverage JSON-RPC communication to control complex agent workflows from Claude Code, VS Code, CI pipelines, or custom scripts without direct dependency on Ruflo's internal implementation.

Understanding Ruflo's MCP Architecture

The Three-Layer Integration Stack

Ruflo v3 organizes external integrations into three distinct layers that provide flexible connectivity options.

The Orchestration Layer hosts the MCPServer class in v3/mcp/server.ts, managing the tool registry, session handling, and transport adapters. This layer accepts JSON-RPC requests from Claude Code, Codex, VS Code, and CI pipelines over stdio, HTTP, or WebSocket connections.

The Plugins & Extensions Layer contains domain-specific adapters such as the TeammateTool and Code-Intelligence plugins. These register additional MCP tools via their registerMCPTools functions, exposing specialized workflows for team-based coordination and automated testing.

The CLI / SDK Layer provides thin wrappers in bin/cli.js that forward commands to the MCP server. This maintains a familiar command-line experience while ensuring all operations route through the standardized protocol.

Core Components and File Paths

Key files define the integration surface area for Ruflo's MCP implementation:

• v3/mcp/server.ts - Contains the MCPServer implementation handling transport initialization and tool routing
• v3/mcp/tools/README.md - Documents built-in MCP tools including swarm_init and memory_search
• v3/implementation/init/README.md - Describes MCP server configuration via .mcp.json and startup flags
• bin/cli.js - Entry point for the thin CLI wrapper used by npx ruflo@latest

Starting the MCP Server for Tool Integration

NPX Quick Start

The fastest way to expose Ruflo's capabilities to external tools is through the stdio transport using npx.

# Start Ruflo's MCP server with default stdio transport

npx ruflo@latest mcp start

This command initializes the MCPServer and begins listening for JSON-RPC messages on standard input. Any MCP client that spawns this process can immediately access tools like swarm_init, agent_spawn, and memory_store.

Configuration via .mcp.json

For persistent setups, Ruflo supports configuration through .mcp.json files as documented in v3/implementation/init/README.md.

{
  "transport": "http",
  "port": 3000,
  "cors": true,
  "tools": {
    "swarm": true,
    "memory": true,
    "plugins": ["teammate", "code-intelligence"]
  }
}

This configuration switches the transport to HTTP on port 3000, enabling web-based integrations and cross-origin requests for browser-based clients.

Connecting Claude Code and AI Assistants

Claude Code MCP Configuration

Claude Code discovers Ruflo's capabilities through MCP server configuration. Add the following to your Claude Code settings:

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Once configured, Claude Code lists Ruflo's tools in the Tool Picker, allowing direct invocation of swarm_init and memory_search without leaving the chat interface.

Programmatic Access from Node.js

For programmatic integration, use the MCP client SDK to connect to Ruflo's server:

import { createMCPClient } from '@claude-flow/mcp-client';

// Connect to running Ruflo server via stdio
const client = await createMCPClient({ transport: 'stdio' });

// Initialize a hierarchical swarm with 6 agents
const swarmResult = await client.request('swarm_init', {
  topology: 'hierarchical',
  maxAgents: 6,
  strategy: 'specialized'
});

console.log('Swarm ID:', swarmResult.swarmId);

This pattern works with any Node.js application needing to orchestrate agent swarms through Ruflo's infrastructure.

Extending Functionality with Plugins

Teammate Tool for Multi-Agent Coordination

The Teammate plugin extends Ruflo with team coordination capabilities documented in v3/plugins/teammate-plugin/README.md.

import { createTeammateBridge } from '@claude-flow/teammate-plugin';

const bridge = await createTeammateBridge({ fallbackToMCP: true });

// Create a hierarchical development team
const team = await bridge.spawnTeam({
  name: 'dev-team',
  topology: 'hierarchical',
  maxTeammates: 5,
  planModeRequired: true
});

// Spawn a specialized coder teammate
const coder = await bridge.spawnTeammate({
  name: 'coder-1',
  role: 'coder',
  prompt: 'Implement OAuth2 login flow',
  teamName: team.name,
  model: 'sonnet',
  allowedTools: ['Edit', 'Write', 'Read']
});

The bridge automatically registers MCP tools via registerMCPTools, making these team operations available to any connected client.

Code Intelligence for Automated Analysis

The Code-Intelligence plugin exposes analysis tools for automated testing and code review as described in v3/plugins/code-intelligence/README.md.

// Build AgentInput for Claude Code's Task tool
const agentInput = bridge.buildAgentInput({
  name: 'tester-1',
  role: 'tester',
  prompt: 'Write integration tests for the login flow',
  teamName: team.name,
  model: 'haiku'
});

This generates the proper input structure for Claude Code's native Task tool, bridging Ruflo's agent management with IDE-specific interfaces.

CI/CD Pipeline Integration

For automated workflows, Ruflo's CLI wrapper in bin/cli.js enables direct integration with GitHub Actions and other CI systems.

name: Code Intelligence
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start Ruflo MCP
        run: npx ruflo@latest mcp start &
      - name: Run analysis
        run: |
          npx ruflo@latest cli --agent code-intelligence \
            --task "Detect dead code in src/**/*.ts"

The CI job starts Ruflo's MCP server in the background, then invokes the code-intelligence agent via the thin CLI wrapper, which forwards the request through the MCP protocol. This pattern works for any automated testing or deployment pipeline that can run Node.js commands.

Summary

• Ruflo exposes all capabilities via MCP: The MCPServer class in v3/mcp/server.ts provides JSON-RPC access to swarm coordination, memory services, and plugins through stdio, HTTP, or WebSocket transports.
• Zero-install integration: Use npx ruflo@latest mcp start to immediately expose Ruflo's tool registry to Claude Code, VS Code, or custom scripts without local installation.
• Plugin ecosystem extends functionality: The Teammate plugin (v3/plugins/teammate-plugin/README.md) and Code-Intelligence plugin (v3/plugins/code-intelligence/README.md) register additional MCP tools for team coordination and automated analysis.
• Language-agnostic protocol: Any client supporting MCP can invoke swarm_init, memory_search, and plugin tools via standard JSON-RPC requests over the configured transport.

Frequently Asked Questions

What transport protocols does Ruflo's MCP server support?

Ruflo's MCP server supports three transport protocols: stdio (default, for local process spawning), HTTP (for web-based clients and REST-like interactions), and WebSocket (for persistent bidirectional connections). Configure the transport in .mcp.json as documented in v3/implementation/init/README.md, or via command-line flags when starting the server.

Can I use Ruflo with VS Code or other IDEs besides Claude Code?

Yes. Any IDE or editor that implements the Model Context Protocol can connect to Ruflo. VS Code, Cursor, and other MCP-compatible environments can add Ruflo by configuring the server command npx ruflo@latest mcp start in their MCP server settings, similar to the Claude Code configuration. Once connected, these IDEs can invoke swarm_init and other tools directly from their AI assistant panels.

How do I expose custom functionality through Ruflo's MCP server?

Create a plugin that implements the registerMCPTools function to expose your functionality as MCP tools. Place your plugin code in the v3/plugins/ directory following the pattern shown in v3/plugins/teammate-plugin/README.md. When Ruflo's MCPServer starts, it automatically discovers and registers tools from enabled plugins, making them available to all connected clients via the standard JSON-RPC interface.

Does the Ruflo CLI require the MCP server to be running separately?

No. The CLI wrapper in bin/cli.js automatically handles the MCP server lifecycle. When you run npx ruflo@latest cli, the thin client checks for a running server and starts one if necessary, forwarding your commands as JSON-RPC requests. This ensures the command-line experience remains seamless while maintaining the architectural benefits of the MCP protocol.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}