PiEEG Agent & Buddy·LSL · MCP (:8765/mcp) · Web Bluetooth

Language-Sized Neural Perception & MCP Tooling

LLMs reason at ~1 Hz; EEG arrives at 250 to 500 Hz. PiEEG Agent bridges the rate mismatch with a 5-tier perception cascade that compresses raw microvolts into verifiable tool calls, L2 + group-lasso pattern classifiers, session effect sizes, and an MCP doorway for the editor or copilot you already run.

Open Buddy (Browser AI)Interactive MCP Stage Connect Cursor / Claude / VS Code GitHub Repo

5-Tier Perception Cascade MCP Server (streamable-HTTP, SSE, stdio) L2 + Group-Lasso LORO-CV Classifiers 4-Stage Gated Device Control Provider-Agnostic (Cloud or Local Ollama)

PerceptionCascade · 250 Hz → 8 Hz → 1 Hz → Sparse Tools

LSL / WebBLE ring (60s)0 raw floats sent to LLM

T0 · RAW250 Hz

float32 µV · 60s ring

LLM: Never sent

T1 · FEATURES8 Hz

FFT δθαβγ + quality

LLM: Via tools

T2 · STATE1 Hz

focus · relax · engage

LLM: On demand

T3 · EVENTSSparse

2s dwell · hysteresis

LLM: Context log

T4 · REASONOn query

MCP / Copilot tools

LLM: JSON verdict

T0 · 250 Hz Raw µV (ring buffer)

T1/T2 · 8 Hz PSD + 1 Hz State

T3/T4 · Hysteresis Events & Tool Pulls

Live Tool PullNeuralTools · read-only

> get_channel_quality()

{ status: "good", quality: 0.97, line_ratio: 0.018, bad: [] }

relax (session)0.78

focus (session)0.41

alpha peak (IAF)10.2 Hz

signal quality0.97

Device gate: locked (read-only)Trace cascade

[01 · Interactive AI Architecture][02 · Live MCP Portal & Host Q&A][03 · Host Configs & CLI][04 · 22 Tool Contracts & Safety Gate][05 · PiEEG Agent vs Buddy]

[01 · AI & AGENT ARCHITECTURE]

Trace the signal from 250 Hz ring buffer to LLM tool call

Select a subsystem to inspect how raw microvolts become language-sized tool verdicts, cross-validated classifiers, and gated device commands. Hover any specification row to trace its nodes.

Highlight

Live output preview

Values in the live panel are simulated to illustrate the runtime contract of each Agent subsystem.

[02 · MODEL CONTEXT PROTOCOL DOORWAY]

One live EEG server. Every AI host you already trust.

Click any question and any host node below to watch JSON-RPC tool calls travel from Claude, ChatGPT, Cursor, VS Code, or a local Ollama agent into PiEEG Agent and return grounded neural metrics.

[03 · HOST CONFIGURATION & CLI WORKFLOW]

Wire your editor or terminal to the live stream in 60 seconds

Install with a single command (no Node.js required; the React web UI is prebuilt). Start an LSL stream from hardware or --mock, then open the web notebook or attach an MCP host.

Full MCP Host Guide

MCP Host Configuration

Default: http://127.0.0.1:8765/mcp

1. Start LSL stream & MCP server

# Terminal 1 — hardware or synthetic LSL stream
pieeg-server --lsl          # or: pieeg-server --mock --lsl

# Terminal 2 — start MCP server (skip for stdio hosts like Claude Desktop)
pieeg-agent mcp             # listens on http://127.0.0.1:8765/mcp

2. Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "pieeg": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Start pieeg-server --lsl and pieeg-agent mcp in two terminals, save .cursor/mcp.json, enable 'pieeg' in Cursor Customize → MCP, and ask: how's my signal?

streamable-httpDefault · :8765/mcp

--transport stdioHost spawns process

--transport sseLegacy · :8765/sse

One-Line Install (Linux / macOS / WSL)

curl -sSL https://raw.githubusercontent.com/pieeg-club/PiEEG-agent/main/install.sh | bash

Windows: git clone https://github.com/pieeg-club/PiEEG-agent.git && cd PiEEG-agent && install.cmd

Six CLI Modes

$ pieeg-agent streams

Discover active Lab Streaming Layer (LSL) outlets on the local network.

$ pieeg-agent monitor

Live terminal readout of band powers, channel quality, and state indices (no LLM required).

$ pieeg-agent ask "am I focused?"

One-shot question answered from a fresh tool call against the live stream.

$ pieeg-agent chat

Interactive multi-turn terminal conversation with pattern training and session tools.

$ pieeg-agent web

Launch FastAPI + prebuilt React notebook UI on http://localhost:8000 (no Node.js needed).

$ pieeg-agent mcp

Serve all read and decode tools over MCP at http://127.0.0.1:8765/mcp (no API key needed).

[04 · TOOL CONTRACTS & HARDWARE SAFETY GATE]

Every claim grounded in a typed tool call. Hardware locked by default.

Whether accessed from the web UI, terminal CLI, or an external MCP host, the agent reasons exclusively through four modular tool collections. Unknown tool names or invalid parameters return structured JSON errors rather than crashing the loop.

NeuralTools · Live Cascade Senses

Always On · Read-Only

Side-effect-free reads over the 60-second PerceptionCascade ring buffer. Never blocks LSL ingestion.

get_neural_state

Smoothed ~1 Hz focus, relax, and engagement (0..1 within-session), dominant band, quality, and warming_up flag.

get_band_powers

Relative δ, θ, α, β, γ distribution across the headset and per-channel breakdown.

get_channel_quality

Per-channel verdict (good, flat, rail, noisy, line) with RMS amplitude (µV) and 50/60 Hz line ratio.

get_recent_events

Hysteresis-debounced state transitions (0.70/0.30 thresholds, 2.0s dwell, 0.50 quality floor).

summarize_last

Compact natural-language status line summarizing the latest window.

DecodeTools · Classifiers, PSD & Connectivity

Stateful · PatternStore

Taps the cascade at 8 Hz to train L2 + group-lasso detectors, compute spectral biomarkers, and measure coupling.

start / record_segment / finish_pattern_training

Capture contrastive REST vs ACTIVE reps (1-20s, 2-8 reps) and fit an L2 + group-lasso classifier.

list / detect / explain / forget_pattern

Inspect LORO-CV balanced accuracy, live PatternBank probabilities, and per-electrode importance weights.

analyze_spectrum

Individual Alpha Frequency (IAF), aperiodic 1/f slope, θ/β ratio, spectral entropy, and frontal α asymmetry.

connectivity

Cross-channel Pearson r over log band-power envelopes (256-frame rolling history) with hub ranking.

find_artifacts

Recent single/double eye blinks, jaw clenches, and high-amplitude motion transients.

Session, Notebook & Literature Tools

Reproducible Science

Record labelled experiment blocks, compute within-session effect sizes, and export executable Jupyter notebooks.

record / list / analyze_session

Capture a 2 to 120s labelled window with full band statistics, state trajectories, and quality summary.

compare_sessions

Contrast any two recorded sessions using within-session Cohen's d standardized mean differences.

create_jupyter_notebook

Generate a ready-to-run .ipynb notebook with ROC curves, confusion matrices, and band evolution plots.

search_web & fetch_url

Query PubMed and Wikipedia or fetch from trusted scientific publisher domains.

search_docs & fetch_doc

Search and retrieve official PiEEG hardware and software documentation.

ActuatorTools · Gated Device Control

Opt-In · ActionGate

Absent by default. Exposed as dry-run previews with --allow-actions, and executed only with --execute.

server_status & list_webhooks

Read-only inspection of sample rate, active filter corners, LSL/recording state, and webhook rules.

set_filter

Enable/disable or retune Butterworth bandpass (strictly validates 0 < lowcut < highcut <= 125 Hz).

start_recording & stop_recording

Start or stop timestamped CSV recording on pieeg-server.

apply_register_preset

Switch ADS1299 channels between 'normal', 'internal_short', 'test_signal', or 'temp_sensor' (no raw hex writes).

configure_osc

Enable or retarget the server's VRChat / TouchDesigner UDP OSC bridge ('chatbox', 'parameters', 'both').

ActionGate Policy (pieeg_agent/server/gate.py)

Three explicit permission tiers for hardware control

Audit log: ~/.pieeg-agent/audit.jsonl

1. Default (Observational)Read-Only

$ pieeg-agent web / mcp

ActuatorTools are not registered in the toolset. The model can inspect quality, state, spectra, connectivity, and patterns, but cannot see or call any device command.

2. Dry-Run PreviewPreview Only

$ pieeg-agent web --allow-actions

Exposes curated actuator tools, validates arguments against the allowlist and frequency bounds, logs the intent, and returns a dry-run preview envelope without sending packets to the board.

3. Gated ExecutionAllowlist + Cooldown

$ pieeg-agent web --allow-actions --execute

Commands pass Allowlist → Parameter Bounds → Per-Rule Cooldown → Dry-Run Check → Audit Log before reaching ws://localhost:1616. Raw register writes remain locked.

[05 · DEPLOYMENT MODES & LLM PROVIDERS]

One architecture, two runtimes: Python Server Agent vs Browser Buddy

Run buddy.pieeg.com for instant zero-install Web Bluetooth/Serial pairing in a browser tab, or run pieeg-agent alongside pieeg-server --lsl for MCP hosting, Raspberry Pi SPI shields, and Jupyter notebook generation.

PiEEG Agent (Python + LSL + MCP) vs Buddy (Browser-Native)

Shared PerceptionCascade & LORO-CV Classifier Design

Capability	PiEEG Agent (Python / LSL / MCP)	Buddy (buddy.pieeg.com)
Runtime	Python 3.10+ process (FastAPI + prebuilt React UI on :8000, CLI, and MCP server on :8765)	100% client-side in a Chromium browser tab at buddy.pieeg.com (zero install)
Signal Source	Any Lab Streaming Layer (LSL) outlet: pieeg-server --lsl (SPI, BLE, USB), OpenBCI, Muse, or --mock	Direct Web Bluetooth (IronBCI 8/16, Octopus 16), Web Serial (IronBCI-32), or in-tab synthetic demo
MCP Server (:8765/mcp)	Yes — serves tools over streamable-HTTP, SSE, or stdio to Cursor, VS Code, Claude, and Codex	No — self-contained browser copilot and live brain panel
Pattern Training & Senses	Full T0-T3 cascade, L2 + group-lasso LORO-CV patterns, IAF/1/f spectrum, connectivity	Same T0-T3 cascade, L2 + group-lasso LORO-CV patterns, IAF/1/f spectrum, connectivity in JS
Sessions & .ipynb Export	Persistent ~/.pieeg-agent store, Cohen's d session comparison, and auto-generated .ipynb notebooks	Patterns persisted in browser localStorage; live session trend charts in the brain panel
Hardware Control	Optional behind 4-stage ActionGate (--allow-actions preview / --execute)	Strictly read-only (observes and explains; never mutates hardware)

7 Supported LLM Providers (Stdlib HTTP, Zero Vendor SDKs)

Both PiEEG Agent and Buddy normalize tool calls across Anthropic Messages and OpenAI-compatible Chat Completions without heavy third-party SDK dependencies. Use a cloud key, run 100% offline with Ollama or LM Studio, or test with the built-in Echo simulator.

AnthropicClaude Sonnet / Opus via Messages API

ANTHROPIC_API_KEY

OpenAIGPT-4o / o-series via Chat Completions

OPENAI_API_KEY

GroqLow-latency Llama / Mixtral tool calling

GROQ_API_KEY

Together AIOpen-weights hosted models

TOGETHER_API_KEY

Ollama100% local inference on your machine

None

LM StudioLocal OpenAI-compatible server

None

EchoDeterministic tool exerciser, zero keys

None

Video: Live pattern training, spectral inspection, and natural-language Q&A in PiEEG Agent.

Start in the browser or attach your MCP host

Open Buddy at buddy.pieeg.com for zero-install browser pairing, or install pieeg-agent to expose live EEG tools to Cursor, Claude, and VS Code.

Open Buddy (Browser)PiEEG-agent on GitHub Agent & MCP Docs Discord Community

// Research and UX prototyping tool. Not a medical device. All state indices are within-session relative.

PiEEG Cloud →PiEEG Server →MCP Release Note →Buddy Release Note →

Company

Products & Platforms

Academy

Resources & Community

Language-Sized Neural Perception & MCP Tooling

Trace the signal from 250 Hz ring buffer to LLM tool call

Live output preview

One live EEG server. Every AI host you already trust.

Wire your editor or terminal to the live stream in 60 seconds

Six CLI Modes

Every claim grounded in a typed tool call. Hardware locked by default.

NeuralTools · Live Cascade Senses

DecodeTools · Classifiers, PSD & Connectivity

Session, Notebook & Literature Tools

ActuatorTools · Gated Device Control

Three explicit permission tiers for hardware control

One architecture, two runtimes: Python Server Agent vs Browser Buddy

7 Supported LLM Providers (Stdlib HTTP, Zero Vendor SDKs)

Start in the browser or attach your MCP host