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

> Easily integrate Ruflo with other tools using the Model Context Protocol. Connect via stdio HTTP or WebSocket for seamless integration.

- Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/v3/mcp/server.ts) - Contains the `MCPServer` implementation handling transport initialization and tool routing
- [`v3/mcp/tools/README.md`](https://github.com/ruvnet/ruflo/blob/main/v3/mcp/tools/README.md) - Documents built-in MCP tools including `swarm_init` and `memory_search`
- [`v3/implementation/init/README.md`](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/init/README.md) - Describes MCP server configuration via [`.mcp.json`](https://github.com/ruvnet/ruflo/blob/main/.mcp.json) and startup flags
- [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/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.

```bash

# 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`](https://github.com/ruvnet/ruflo/blob/main/.mcp.json) files as documented in [`v3/implementation/init/README.md`](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/init/README.md).

```json
{
  "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:

```json
{
  "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:

```typescript
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`](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/teammate-plugin/README.md).

```typescript
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`](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md).

```typescript
// 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`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js) enables direct integration with GitHub Actions and other CI systems.

```yaml
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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/teammate-plugin/README.md)) and Code-Intelligence plugin ([`v3/plugins/code-intelligence/README.md`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/.mcp.json) as documented in [`v3/implementation/init/README.md`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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.