floop MCP Server Integration

March 14, 2026 · View on GitHub

Overview

The floop mcp-server command exposes floop as a Model Context Protocol (MCP) server, enabling deep integration with AI coding tools. This allows AI agents to query active behaviors and capture corrections automatically, creating a true feedback loop without manual intervention.

Supported AI Tools

Continue.dev (Agent mode)
Cursor (Composer and Agent modes)
Cline (formerly Claude Dev)
Windsurf / Cascade
GitHub Copilot (Agent mode - via VSCode extension)

Benefits

Bidirectional Integration: Tools can both read behaviors AND write corrections automatically
Context-Aware: Behaviors activate based on current file, task, and environment
Zero Manual Overhead: No need to run floop commands manually
Automatic Learning: Corrections captured during development are immediately available
Consistent Behavior: All AI agents see the same learned behaviors

Quick Start

1. Start the MCP Server

# Start server in your project directory
cd /path/to/your/project
floop mcp-server

# Or specify project root explicitly
floop mcp-server --root /path/to/project

The server runs as a stdio-based JSON-RPC service, reading requests from stdin and writing responses to stdout.

2. Configure Your AI Tool

Add floop to your AI tool's MCP server configuration (see tool-specific sections below).

3. Use MCP Tools in Agent Mode

Your AI tool can now invoke floop tools:

floop_active - Get behaviors relevant to current context
floop_learn - Capture corrections during development
floop_feedback - Signal whether a behavior was helpful or contradicted
floop_list - Browse all learned behaviors
floop_deduplicate - Find and merge duplicate behaviors
floop_backup - Export graph state to a backup file
floop_restore - Import graph state from a backup file
floop_connect - Create edges between behaviors
floop_validate - Check graph for consistency issues
floop_graph - Visualize the behavior graph

Tool Reference

floop_active

Get active behaviors for the current context.

Parameters:

file (string, optional): Current file path
task (string, optional): Task type (e.g., "development", "testing", "refactoring")

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_active",
    "arguments": {
      "file": "cmd/floop/main.go",
      "task": "development"
    }
  },
  "id": 1
}

Vector pre-filtering: When local embeddings are configured (see EMBEDDINGS.md), floop_active uses vector similarity search to pre-filter candidate behaviors before applying spreading activation. The vector index uses LanceDB (embedded vector database) with a brute-force fallback when CGO is unavailable. This finds semantically relevant behaviors even when their when predicates don't exactly match the current context. The system falls back to loading all behaviors when embeddings are unavailable.

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "file": "cmd/floop/main.go",
      "language": "go",
      "task": "development"
    },
    "active": [
      {
        "id": "behavior-a1b2c3d4",
        "name": "use-cobra-for-cli",
        "kind": "directive",
        "content": {
          "canonical": "Use spf13/cobra for CLI command structure"
        },
        "confidence": 0.95,
        "when": {
          "language": "go",
          "file_pattern": "cmd/*/main.go"
        }
      }
    ],
    "count": 1
  },
  "id": 1
}

floop_learn

Capture a correction and extract a reusable behavior.

Parameters:

right (string, required): What should have been done instead
wrong (string, optional): What the agent did that needs correction (stored as provenance only, not injected into behavior content)
file (string, optional): Relevant file path for context
task (string, optional): Current task type for context
auto_merge (boolean, optional): Enable automatic merging of duplicate behaviors (default: false)
tags (string array, optional): Additional tags to apply to the behavior, merged with inferred tags (max 5). Tags are normalized (lowercased, deduplicated) and dictionary synonyms are resolved (e.g., "golang" becomes "go"). Useful for skill packs that need deterministic tag-based filtering.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_learn",
    "arguments": {
      "wrong": "Used fmt.Println for error logging",
      "right": "Use fmt.Fprintln(os.Stderr, err) for error output",
      "file": "cmd/floop/main.go",
      "tags": ["error-handling", "logging"]
    }
  },
  "id": 2
}

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "correction_id": "correction-x7y8z9",
    "behavior_id": "behavior-e5f6g7h8",
    "scope": "local",
    "auto_accepted": true,
    "confidence": 0.85,
    "requires_review": false,
    "message": "Learned behavior (local): error-logging-to-stderr"
  },
  "id": 2
}

Scope Classification:

The scope field indicates where the behavior was stored. Behaviors are automatically routed to the correct store based on their activation conditions:

"local" — Behavior has project-specific conditions (file_path or environment in its When predicate). Stored in ./.floop/ only.
"global" — Behavior has universal conditions (language-only, task-only, or no conditions). Stored in ~/.floop/ only.

Each behavior goes to exactly one store — no duplication. Providing a file parameter with a directory path (e.g., "internal/store/file.go") typically produces a local behavior, while omitting file or providing a bare filename produces a global one.

floop_feedback

Provide session feedback on a behavior — signal whether it was helpful or contradicted.

Parameters:

behavior_id (string, required): ID of the behavior to provide feedback on
signal (string, required): "confirmed" (behavior was helpful) or "overridden" (behavior was contradicted)

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_feedback",
    "arguments": {
      "behavior_id": "behavior-a1b2c3d4",
      "signal": "confirmed"
    }
  },
  "id": 5
}

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "behavior_id": "behavior-a1b2c3d4",
    "signal": "confirmed",
    "message": "Recorded 'confirmed' feedback for behavior-a1b2c3d4"
  },
  "id": 5
}

How it works: Feedback signals feed into the relevance scoring model's feedback component (15% weight). Behaviors that are consistently confirmed get boosted; those that are consistently overridden get suppressed. This closes the feedback loop — behaviors don't just activate, they adapt based on whether they actually helped.

floop_list

List all behaviors or corrections.

Parameters:

corrections (boolean, optional): If true, list corrections instead of behaviors (default: false)
tag (string, optional): Filter behaviors by tag (exact match)

Example Request (list behaviors):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_list",
    "arguments": {}
  },
  "id": 3
}

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "behaviors": [
      {
        "id": "behavior-a1b2c3d4",
        "name": "use-cobra-for-cli",
        "kind": "directive",
        "confidence": 0.95,
        "source": "learned",
        "created_at": "2026-01-28T10:30:00Z"
      },
      {
        "id": "behavior-e5f6g7h8",
        "name": "error-logging-to-stderr",
        "kind": "directive",
        "confidence": 0.85,
        "source": "learned",
        "created_at": "2026-01-28T11:15:00Z"
      }
    ],
    "count": 2
  },
  "id": 3
}

Example Request (list corrections):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_list",
    "arguments": {
      "corrections": true
    }
  },
  "id": 4
}

floop_deduplicate

Find and merge duplicate behaviors in the store.

Parameters:

dry_run (boolean, optional): If true, only report duplicates without merging (default: false)
threshold (number, optional): Similarity threshold for duplicate detection (0.0-1.0, default: 0.9)
scope (string, optional): Scope of deduplication: local, global, or both (default: both)

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_deduplicate",
    "arguments": {
      "dry_run": true,
      "threshold": 0.85
    }
  },
  "id": 6
}

floop_backup

Export full graph state (nodes + edges) to a backup file.

Parameters:

output_path (string, optional): Output file path (default: ~/.floop/backups/floop-backup-TIMESTAMP.json)

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_backup",
    "arguments": {}
  },
  "id": 7
}

floop_restore

Import graph state from a backup file (merge or replace).

Parameters:

input_path (string, required): Path to backup file to restore
mode (string, optional): Restore mode: merge (skip existing, default) or replace (clear first)

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_restore",
    "arguments": {
      "input_path": "~/.floop/backups/floop-backup-20260211-143005.json.gz",
      "mode": "merge"
    }
  },
  "id": 8
}

floop_connect

Create an edge between two behaviors for spreading activation.

Parameters:

source (string, required): Source behavior ID
target (string, required): Target behavior ID
kind (string, required): Edge type: requires, overrides, conflicts, similar-to, learned-from
weight (number, optional): Edge weight (0.0-1.0, default: 0.8)
bidirectional (boolean, optional): Create edges in both directions (default: false)

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_connect",
    "arguments": {
      "source": "behavior-abc",
      "target": "behavior-xyz",
      "kind": "similar-to",
      "weight": 0.9
    }
  },
  "id": 9
}

floop_validate

Validate the behavior graph for consistency issues (dangling references, cycles, self-references).

Parameters:

No parameters required.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_validate",
    "arguments": {}
  },
  "id": 10
}

floop_graph

Render the behavior graph in DOT (Graphviz), JSON, or interactive HTML format for visualization.

Parameters:

format (string, optional): Output format: dot, json, or html (default: json)

Example Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "floop_graph",
    "arguments": {
      "format": "json"
    }
  },
  "id": 11
}

Configuration Examples

Continue.dev

Add floop to your Continue config at .continue/config.json:

{
  "mcpServers": {
    "floop": {
      "command": "floop",
      "args": ["mcp-server"],
      "cwd": "${workspaceFolder}",
      "env": {}
    }
  }
}

Usage in Continue:

Open Agent mode (Cmd/Ctrl + Shift + P → "Continue: Open Agent")
The agent can now invoke floop_active, floop_learn, and floop_list
Example: "What behaviors are active for this file?" → Agent calls floop_active

Cursor

Add floop to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "floop": {
      "command": "floop",
      "args": ["mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Usage in Cursor:

Open Composer or Agent mode
Reference floop tools: "@floop_active" or ask "What behaviors should I follow?"
Cursor automatically invokes MCP tools when relevant

Cline

Add floop to Cline's MCP settings (accessible via Cline panel → Settings → MCP Servers):

{
  "mcpServers": {
    "floop": {
      "command": "floop",
      "args": ["mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Usage in Cline:

Open Cline panel
Start a task: "Implement user authentication"
Cline automatically queries floop_active for relevant behaviors
When you correct Cline, it can call floop_learn to capture the correction

Windsurf / Cascade

In Windsurf settings, add to MCP server configuration:

{
  "mcp": {
    "servers": {
      "floop": {
        "command": "floop",
        "args": ["mcp-server"],
        "cwd": "${workspaceFolder}"
      }
    }
  }
}

GitHub Copilot (VSCode Extension - Agent Mode)

Add floop to VSCode settings for Copilot's MCP support:

In .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": {
    "floop": {
      "command": "floop",
      "args": ["mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Note: MCP support in GitHub Copilot is in preview. Check GitHub Copilot documentation for the latest status.

Architecture

How It Works

┌─────────────────┐
│   AI Tool       │
│ (Continue/      │
│  Cursor/Cline)  │
└────────┬────────┘
         │ JSON-RPC over stdio
         ↓
┌─────────────────┐
│  floop          │
│  mcp-server     │
└────────┬────────┘
         │
         ├─→ Read: GraphStore (.floop/ directory)
         │        Query behaviors, evaluate context
         │
         └─→ Write: LearningLoop
                  Process corrections, extract behaviors

Protocol Details

Transport: stdio (stdin/stdout)
Protocol: JSON-RPC 2.0
Specification: Model Context Protocol

MCP Methods Implemented

initialize - Protocol handshake, version negotiation
tools/list - Returns available tools
tools/call - Executes a tool with parameters

Data Flow

AI Tool sends JSON-RPC request to stdin
MCP Server parses request, routes to appropriate handler
Handler calls internal floop packages:
- floop_active → internal/activation package
- floop_learn → internal/learning package
- floop_list → internal/store package
MCP Server formats response as JSON-RPC and writes to stdout
AI Tool receives response and uses it in agent execution

Troubleshooting

Server Won't Start

Problem: floop mcp-server exits immediately or shows errors

Solutions:

Ensure floop is initialized: floop init (creates .floop/ directory)
Check --root flag points to correct project directory
Verify floop binary is in PATH: which floop

Tool Not Recognized by AI Tool

Problem: AI tool doesn't see floop tools

Solutions:

Restart your AI tool after adding MCP config
Check MCP config file syntax (valid JSON)
Verify command path is correct (use absolute path if needed)
Check AI tool's MCP server logs for connection errors

Behaviors Not Activating

Problem: floop_active returns empty list

Solutions:

Verify behaviors exist: floop list
Check behavior activation conditions (when predicates)
Ensure file path and task context match behavior conditions
Try: floop active --file path/to/file to test manually

Corrections Not Saving

Problem: floop_learn succeeds but behaviors don't persist

Solutions:

Check .floop/ directory is writable
Verify corrections saved: floop list --corrections
Review learning result: look for auto_accepted or requires_review status

Performance Issues

Problem: MCP server slow to respond

Solutions:

Large .floop/ directory: Consider using floop forget to remove old behaviors
Network latency: Ensure --root points to local filesystem, not network mount
Check for disk I/O issues

Best Practices

1. Use Context-Rich Corrections

When using floop_learn, provide detailed context:

{
  "wrong": "Used var for constant value",
  "right": "Use const for values that never change",
  "file": "internal/store/constants.go"
}

Better than:

{
  "wrong": "Used var",
  "right": "Use const"
}

2. Use Global + Local Storage

Global (~/.floop/): Personal conventions, language preferences
Local (./.floop/): Project-specific patterns, team conventions

# Initialize both
floop init          # Local
floop init --global # Global

The MCP server queries both stores and merges results (local takes precedence).

Automatic scope routing: When using floop_learn via MCP, behaviors are automatically classified and routed to the correct store based on their activation conditions (see Scope Classification above). You don't need to specify scope manually.

3. Keep Behaviors Focused

Use floop merge to combine similar behaviors instead of accumulating many small ones.

Advanced Usage

Custom Project Root

If your AI tool runs in a different directory than your project:

{
  "mcpServers": {
    "floop": {
      "command": "floop",
      "args": ["mcp-server", "--root", "/absolute/path/to/project"]
    }
  }
}

Multiple Projects

Run separate MCP servers for different projects by configuring multiple MCP server entries:

{
  "mcpServers": {
    "floop-project-a": {
      "command": "floop",
      "args": ["mcp-server", "--root", "/path/to/project-a"]
    },
    "floop-project-b": {
      "command": "floop",
      "args": ["mcp-server", "--root", "/path/to/project-b"]
    }
  }
}

Debugging MCP Communication

To see JSON-RPC messages:

# Manual test
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | floop mcp-server

# Expected output
{"jsonrpc":"2.0","result":{"tools":[...]},"id":1}

Or use the --json flag for structured output:

floop active --json --file cmd/floop/main.go

floop learn --right "what it should do" --file path/to/file

Explore Behaviors: floop list to see what's been learned
Manually Learn: floop learn --right "what to do" to add corrections
Curate: Use floop forget, floop merge, floop deprecate to manage behaviors
Prompt Generation: floop prompt to generate AI-readable behavior summaries

For more details, see the floop documentation.

Resources

Generated by floop - The feedback loop for AI coding agents