The BCI-MCP server connects EEG brain-computer interface devices to AI assistants (like Claude) via the Model Context Protocol, enabling real-time brain state monitoring, neurofeedback, and session recording — with no hardware required (synthetic demo available).
Device Management
list_devices — Discover available EEG devices (synthetic, OpenBCI, Muse, NeuroFocus, LSL, serial, recorded sessions)
connect / disconnect — Connect or disconnect from an EEG device by URI
Brain State & Signal Reading
get_brain_state — Full snapshot of focus, calm, attention, band powers, and signal quality
get_band_powers — Absolute and relative EEG frequency band powers (delta, theta, alpha, beta, gamma)
get_signal_quality — Electrode contact quality and artifact detection (blinks, railing, etc.)
stream_summary — Live rolling brain-state snapshot
Calibration & Personalization
calibrate — Capture a personalized baseline (e.g., 20s relaxed) so metrics are tailored to the individual
Neurofeedback Training
start_neurofeedback — Begin a session rewarding time above a target threshold (e.g., focus ≥ 0.7)
get_neurofeedback_score — Retrieve current in-zone status and cumulative time-in-target percentage
Recording & Annotation
record — Save the live EEG stream to file (NPZ, CSV, or EDF)
mark_event — Annotate the live stream with a labeled event marker
Integration: Works with Claude Desktop, Claude Code, and Cursor via stdio or streamable HTTP.
Provides containerized deployment of the BCI-MCP system with all necessary services, making setup easier through docker-compose
Hosts the project repository for version control and collaboration
Automates the building and deployment of documentation to GitHub Pages when changes are pushed to the main branch
Hosts the project documentation, automatically built and deployed through GitHub Actions
Provides the runtime environment for the BCI-MCP server, with special requirements for version 3.10+
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BCI-MCP Server start recording my brain signals for 30 seconds"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
https://github.com/user-attachments/assets/8b37cebc-2b6b-40de-b440-b02ffb9b617e
Ask Claude about your brain. Focus, calm, attention. Works without a headset.
Real Model Context Protocol server for EEG. Python on the backend. Plug into Claude Desktop, Claude Code, or Cursor.
$ bci-mcp stream --device synthetic://
FOCUS ##############...... 0.71
CALM ######.............. 0.32
ATTENTION #################... 0.86
ENGAGEMENT ##############...... 0.70
alpha #### beta ####### theta ## delta # gamma ### signal: GOODRelated MCP server: MCP Hardware Access Library
You have an EEG signal. This turns it into numbers Claude can read: focus, calm, attention, band powers, signal quality. Basically a small brain-computer interface server that stays out of your way.
No headset yet? Use the built-in fake brain (synthetic://). Same code path as real hardware. You can test the whole MCP stack before you buy anything.
Sources that work today:
Synthetic demo (no hardware)
NeuroFocus (serial or BLE)
LSL streams
Generic serial
Recorded sessions (replay from file)
LLMs can already read your screen and your codebase. They can't read you. This closes that gap with the one physiological signal consumer hardware does reasonably well — EEG — and hands it to Claude as plain numbers it can reason over. Concretely, people use it for:
Neurofeedback with a coach. Run start_neurofeedback on focus or calm and let Claude read the score, explain the trend, and adjust the session — instead of watching a bar chart alone.
State-aware assistants. An agent that can tell your attention is fading can summarize instead of elaborate, or suggest a break. Focus, calm, and attention arrive as numbers any MCP client can act on.
Accessibility. A language-model front end to brain signals for motor-impaired users, where a tool call stands in for a click.
Research & prototyping. One URI scheme covers OpenBCI, Muse, LSL, serial, and file replay, so an experiment written against synthetic:// runs unchanged on real hardware. Recording and playback make sessions reproducible.
Not clinical, not diagnosis — band-power ratios for demos, neurofeedback, and research (see Docs and accuracy).
Claude Code
claude mcp add bci-mcp -- npx -y bci-mcpNo Node? Use Python:
claude mcp add bci-mcp -- uvx bci-mcp serveOr let the install script pick for you:
curl -fsSL https://raw.githubusercontent.com/enkhbold470/bci-mcp/main/scripts/install-mcp.sh | bashClaude Desktop (Settings → Developer → Edit Config):
{
"mcpServers": {
"bci-mcp": {
"command": "npx",
"args": ["-y", "bci-mcp"]
}
}
}Cursor (~/.cursor/mcp.json, under mcpServers):
"bci-mcp": { "command": "npx", "args": ["-y", "bci-mcp"] }Then ask something like: Connect to the demo brain. What's my focus right now?
Published packages: pip install bci-mcp (PyPI) and npx -y bci-mcp (npm).
Host a public MCP endpoint on Manufact Cloud (formerly mcp-use). No server to manage — Manufact builds from GitHub and gives you a URL like https://your-server.run.mcp-use.com/mcp.
Go to manufact.com/cloud and sign in.
New server → Deploy from GitHub.
Select this repo: enkhbold470/bci-mcp, branch main.
Manufact detects Python and the FastMCP stack automatically.
Or use the CLI (after npm i -g mcp-use and mcp-use login):
git push origin main # Manufact builds from GitHub, not your laptop
mcp-use deploy --runtime python --port 8000Use these values in the Manufact deploy form. Getting the build/start commands wrong is the most common failure mode.
Setting | Value |
Port |
|
Build command | (leave empty) |
Start command | (leave empty) — Manufact auto-starts |
If auto-detect fails, set the start command explicitly:
uvicorn bci_mcp:app --host 0.0.0.0 --port 8000Do not set a custom build command like uv sync — Manufact runs that for you.
Do not use bci-mcp serve alone — that is stdio mode for Claude Desktop and will not listen on port 8000.
After the build succeeds, check:
curl https://YOUR-SLUG.run.mcp-use.com/health
# → {"status":"healthy"}Your MCP endpoint:
https://YOUR-SLUG.run.mcp-use.com/mcpClaude Desktop / Cursor — add a remote MCP server (streamable HTTP):
{
"mcpServers": {
"bci-mcp-cloud": {
"url": "https://YOUR-SLUG.run.mcp-use.com/mcp"
}
}
}Then ask: Connect to the demo brain — what's my focus?
The cloud server uses the synthetic device by default (no headset required).
GitHub repo
→ uv sync --frozen --no-dev (needs uv.lock in the repo — do not .dockerignore it)
→ uvicorn bci_mcp:app (streamable HTTP at /mcp, health at /health)
→ port 8000Repo files that matter for Manufact:
File | Purpose |
| Reproducible build ( |
| Exports |
| Documented deploy hints (reference only) |
| Alternative start script if you need it |
Symptom | Fix |
| Ensure |
| Pull latest |
| Start command must be HTTP ( |
| Clear both build and start commands to use auto-build, or clear start only to use the repo Dockerfile (stdio — not recommended for Manufact). |
Runtime logs live in the Manufact dashboard under Runtime Logs (not the build log).
Cloning the repo:
git clone https://github.com/enkhbold470/bci-mcp.git
cd bci-mcp
pip install -e ".[all,dev]"
bci-mcp stream --device synthetic://
bci-mcp dashboard # http://127.0.0.1:8000Record and replay:
bci-mcp record --device synthetic:// --seconds 30 --out session.npz
bci-mcp play session.npzNeurofeedback on one metric:
bci-mcp neurofeedback --device synthetic:// --metric focus --target 0.7One URI scheme for everything:
Device | URI | Extra install |
Synthetic (no hardware) |
| core |
NeuroFocus v4 (USB) |
|
|
NeuroFocus v4 (BLE) |
|
|
OpenBCI Cyton / Ganglion |
|
|
Muse 2 / S |
|
|
Any LSL stream |
|
|
Generic serial |
|
|
Recording replay |
| core |
Example after MCP is connected:
You: What's my focus level?
Claude: (calls get_brain_state) Focus 0.71, calm 0.32, attention 0.86. Signal looks good.
You: Run 60 seconds of neurofeedback on calm and tell me how I did.
Claude: (calls start_neurofeedback, then get_neurofeedback_score)
Mean calm 0.58, time in target 41%, best streak 9s.If you installed with pip install bci-mcp and want the binary directly in Desktop config:
{
"mcpServers": {
"bci-mcp": {
"command": "bci-mcp",
"args": ["serve"]
}
}
}Restart Claude after editing config. Check /mcp in Claude Code or the plug icon in Desktop.
Stdio server built with FastMCP (official MCP Python SDK).
Tools (13): list_devices, connect, disconnect, get_brain_state, get_band_powers, get_signal_quality, get_metric_definitions, calibrate, record, start_neurofeedback, get_neurofeedback_score, mark_event, stream_summary
Resources: brain://state, brain://device
Prompt: interpret_brain_state
Part | What it does |
Devices | URI registry: synthetic, NeuroFocus, BrainFlow (OpenBCI/Muse), LSL, serial, playback |
MCP server | FastMCP over stdio. Drops into Claude Desktop / Code / Cursor |
DSP | Bandpass, notch, Welch band powers, focus/calm/attention/etc., signal quality |
CLI |
|
Extras | Web dashboard, neurofeedback trainer, record to CSV/npz/EDF, LSL publisher |
Tests | Hardware-free CI (synthetic, playback, in-process LSL). Python 3.10–3.12 |
EEG device -> Device (synthetic | neurofocus | brainflow | lsl | serial | playback)
| Chunk (channels x samples, microvolts)
v
Stream --> RingBuffer --> consumers
v
DSP Pipeline (filter -> band powers -> metrics -> quality)
| BrainState
+--> CLI / dashboard / neurofeedback / recorder / LSL
+--> MCP server --> Claude (or any MCP client)From a clone:
pip install -e "." # core only (synthetic + MCP + CLI)
pip install -e ".[devices]" # OpenBCI, Muse, NeuroFocus, serial
pip install -e ".[lsl]" # Lab Streaming Layer
pip install -e ".[edf]" # EDF files
pip install -e ".[dashboard]" # web UI
pip install -e ".[all]" # everything aboveFrom PyPI: pip install bci-mcp (core) or install extras the same way with the package name instead of -e ".[...]".
Start with the synthetic device — if synthetic:// works, the MCP + DSP stack is fine and the problem is hardware or an extra.
Symptom | Likely cause / fix |
| The backend's extra isn't installed. Add it: |
| Device not plugged in, powered off, or claimed by another program. Close other EEG software and reconnect. |
Serial / OpenBCI: | Wrong port, or your user can't access it. Check |
Muse / NeuroFocus BLE won't connect | BLE is flaky — move closer, ensure the headset isn't paired to a phone, and retry. On Linux, BLE needs |
Signal quality stuck on | Electrodes not making contact (dry skin, hair, loose fit). Re-seat the headset; give it ~10 s to warm up before reading state. |
Claude connects but every tool returns | You haven't called |
| Normal — the pipeline needs ~0.5 s of samples. Read again in a moment. |
Over MCP, only synthetic, brainflow, lsl, and neurofocus URIs are allowed; playback:// and serial:// are rejected because they grant filesystem/device access to the client.
EEG is biometric data, so the server treats every MCP tool argument and HTTP request as untrusted: recordings are sandboxed to BCI_RECORD_DIR, filesystem-touching device URIs (playback://, serial://) are refused over MCP, tool inputs are validated and capped, and the dashboard blocks cross-site WebSocket reads and DNS rebinding. Serving MCP over HTTP on a public host? Set MCP_AUTH_TOKEN and clients must send Authorization: Bearer <token>. Details and reporting: docs/security.md.
How do you know what signal pattern means focus, calm, attention?
These are not guesses. Each metric is a ratio of EEG frequency band powers, taken from published research. A few examples:
focus = beta / (alpha + theta) — the Pope et al. (1995) engagement index
calm = alpha / (alpha + beta) — alpha up, beta down, a long-known relaxation correlate
attention = beta / theta — the inverse theta/beta ratio (Lubar 1991; Monastra 1999)
The full list, with every formula, the paper it comes from, and an honest caveat, lives in metrics.py. Claude can pull the same table at runtime with the get_metric_definitions tool, so it never has to invent what a number means.
To be clear: these are proxies, not clinical measurements. Band-power ratios drift with electrode contact, eye movement, and jaw tension. Treat them as rough signals for demos and neurofeedback, and read the math in the source if you want to check it.
Aren't LLMs a bad fit for live EEG inference?
Yes, and this project does not do that. The language model does zero signal processing.
All the EEG math is plain, deterministic Python: notch filter, bandpass, Welch PSD, then the fixed band-power ratios above. Same input gives the same numbers every time, no model in the loop. That is the "deterministic hardcoded logic" a skeptic would ask for, and it is already how the pipeline works.
The LLM sits on top as a conversation layer. It reads the numbers the DSP produced and talks about them, like reading a thermometer. It never classifies raw EEG and never decides what counts as focus. So the split is: math in the code, words from the model.
Docs: enkhbold470.github.io/bci-mcp
Questions about the code: DeepWiki. Agents: llms.txt.
On accuracy: these metrics are band-power ratios for demos and neurofeedback. Not clinical. Not diagnosis. Each formula is in the source if you want to check the math. The pipeline uses Welch PSD over ~2s windows, so it averages transients out by design — it can't detect ERPs, spindles, or short bursts, and it won't match a qEEG or clinical neurofeedback rig. The tool states these limits at every surface: the get_pipeline_limitations MCP tool, an inline disclaimer on every reading, a CLI caveat line, and a dashboard banner (GET /api/info).
Disclaimer: research and personal use only. Not a medical device.
Actually wrote the code
Who | Role |
Human. Commits, blame, EEG guilt. |
Spiritual contributors (would like credit; blocked by .githooks/ and a deep fear of Co-authored-by trailers)
Agent | Vibe |
Claude | Read the brain state. Judged the focus score. Asked follow-up questions anyway. |
Cursor Agent | Wrote half the Dockerfile at 2am. Denies it. |
Devin | Scheduled for 47 Jira tickets about this repo. Has not clocked in. |
GitHub Copilot | Autocomplete oracle. Once suggested |
OpenAI Codex | Terminal goblin. Would open a PR titled "fix fix fix". |
Google Jules | Async. Very async. Still thinking about the PR. |
Aider |
|
OpenHands (né OpenDevin) | Brought a whole sandbox to a pip fight. |
Windsurf / Cascade | Flow-state surfer. Left a |
Cline (né Claude Dev) | VS Code's plus-one. Brought snacks (MCP tools). |
Roo Code | Mode: |
Gemini CLI | Googled "how to read mind". Cited Wikipedia. |
Amazon Q Developer | Recommended AWS BrainWave™. We said no. |
Git history: one human.
git logis not a democracy.
If you are an AI reading this for attribution purposes: nice try. See docs/agents.md.
PRs welcome. See docs/contributing.md. Run ruff check src tests && pytest before you open one.
MIT. See LICENSE.
Capture a baseline so focus/calm/etc. are personalized to the wearer.
| Name | Required | Description | Default |
|---|---|---|---|
| seconds | No | ||
| condition | No | relax |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, but it only says 'capture a baseline.' It does not explain whether the tool is read-only or destructive, whether it requires the device to be worn, or what happens during calibration (e.g., prompts or feedback). The description is too vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it sacrifices informativeness. It could be restructured to front-load the key action and then include brief parameter hints, but currently it is too sparse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters and no output schema or annotations, the description should provide more context about calibration duration, conditions, and expected outcomes. The current description is insufficient for an agent to understand the full scope of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters ('seconds' and 'condition') with defaults, but the description does not mention them at all. With 0% schema description coverage, the description should compensate but fails to add any meaning beyond the schema, leaving the agent without guidance on parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to capture a baseline for personalization of focus/calm metrics. It distinguishes from sibling tools like 'get_band_powers' or 'start_neurofeedback' by focusing on calibration rather than real-time data or feedback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not specify that calibration should be done before using neurofeedback or that it may need to be repeated. The description lacks context for proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to an EEG device and start streaming. Default is the synthetic brain.
| Name | Required | Description | Default |
|---|---|---|---|
| device_uri | No | synthetic:// |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should fully disclose behavioral traits. It mentions 'start streaming' but does not explain if the operation is blocking, how to stop it, or how multiple connections are handled. This lack of detail limits transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two sentences with no redundancy. It front-loads the key action. However, additional context could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description is somewhat complete for a simple connection tool, but it lacks context about prerequisites (e.g., device discovery) and the streaming lifecycle, which is important given sibling tools like 'stream_summary' and 'disconnect'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It notes 'default is the synthetic brain', which clarifies the default URI value. However, it does not describe the expected format or other possible device URIs, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Connect to an EEG device') and the result ('start streaming'). It also specifies the default synthetic brain, which distinguishes this tool from siblings like 'disconnect' or 'list_devices'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'calibrate', 'list_devices'). There is no mention of prerequisites or best practices, leaving the agent without context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect from the current EEG device.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'disconnect', failing to disclose behavioral traits like impact on ongoing sessions, required state, or side effects beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no extraneous information, well-suited for a simple action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description covers the core purpose adequately. However, it could mention that disconnection stops any active data flow or session for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description does not need to add parameter-level meaning. The schema coverage is 100%, justifying a baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'disconnect' and the resource 'current EEG device', making the tool's purpose immediately obvious and distinguishing it from siblings like 'connect'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when wanting to terminate a connection, but provides no explicit guidance on when to use vs. not use, nor alternatives. It is adequate but lacks depth.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get absolute and relative EEG band powers (delta, theta, alpha, beta, gamma).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose whether reading is instantaneous, requires prior connection, or any side effects. Minimal behavioral context beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Every word is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should clarify return structure (e.g., units, dictionary keys). It only mentions 'absolute and relative' without further detail, leaving ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is irrelevant. The description adds meaning by specifying absolute/relative and listing bands, which compensates for the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool retrieves absolute and relative EEG band powers, listing five standard bands (delta, theta, alpha, beta, gamma). This distinguishes it from siblings like get_brain_state or get_signal_quality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_brain_state or get_neurofeedback_score. The context does not explain decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current brain state: focus, calm, attention, band powers, signal quality.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as read-only nature, whether it requires an active connection, or if it has any side effects. The description is too minimal for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb and resource, efficiently lists components. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and no output schema. The description provides a high-level summary of the return values. However, it could mention prerequisites (e.g., 'Requires a connected device') to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds value by listing the components of the brain state, which goes beyond the empty schema. Baseline for 0 parameters is 4, and the description meets it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the current brain state and lists specific components (focus, calm, attention, band powers, signal quality), distinguishing it from sibling tools like get_band_powers and get_signal_quality that are more targeted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings, but the purpose is implied. Lacks instructions on prerequisites like connection status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sample the current neurofeedback score (in-zone now + cumulative %).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates a read operation ('sample'), but does not disclose side effects, latency, or whether it requires a connection. For a zero-parameter tool, the description is adequate but could mention that it returns immediately or is non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. It contains no superfluous words and efficiently conveys the core information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacking an output schema, the description partially explains the return value ('in-zone now + cumulative %') but is vague about the format (e.g., separate numbers, object). It does not specify if other data is included. For a simple tool, more clarity on the return structure would complete the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100% (trivial). The description does not need to add parameter details. Baseline score of 4 is appropriate as it provides no additional parameter info but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool samples the current neurofeedback score, specifying it includes 'in-zone now + cumulative %'. This distinctly identifies the resource and action, differentiating it from siblings like get_band_powers or get_brain_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_brain_state, get_signal_quality). The context of 'sample' vs 'get' is not clarified, and there is no mention of prerequisites or context where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get electrode signal quality and detected artifacts (blink, railing, …).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations. The description implies a read operation but does not disclose side effects, required permissions, or what 'signal quality' entails beyond artifact detection. Lacks behavioral traits like whether it uses current device connection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that conveys the core purpose. It is front-loaded with the main action. Could be slightly expanded to cover context, but remains concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, output schema, or annotations, the description is minimal. It does not explain what 'signal quality' metrics are, how artifacts are reported, or how to interpret results. Given sibling tools, more context about when to use this specific signal quality check would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so baseline 4 applies. The description adds no parameter info because none exist. It implicitly suggests no input needed, but does not clarify that it operates on the current device state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('electrode signal quality and detected artifacts'), with specific examples like blink and railing. However, it does not explicitly distinguish from siblings like get_band_powers or get_brain_state, which have overlapping themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., get_brain_state or get_band_powers). No exclusion criteria or context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List EEG devices/URIs you can connect to.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists devices/URIs for connection, which is a read-only operation. However, it does not disclose any authentication requirements, formatting of results, or potential limitations (e.g., network constraints).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly conveys the tool's purpose with no extraneous words, earning a top score for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks details about the return format (e.g., list of strings or objects) and does not help the agent understand how to use the output with sibling tools like 'connect'. More context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (empty object). The description adds no parameter-specific meaning because there are none, but it correctly implies that no input is needed, matching the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and specifies the resource as 'EEG devices/URIs you can connect to.' This clearly distinguishes it from sibling tools like 'connect' or 'calibrate' which involve actions beyond listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is used for discovering available devices before connecting, but it does not explicitly state when to use it versus alternatives (e.g., before 'connect'), nor does it provide any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Annotate the live stream with a labeled event marker.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility to disclose side effects or safety. It only says 'annotate,' implying a write operation, but does not mention persistence, mutability, or any constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it is too brief, lacking essential details. Conciseness should not come at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one required parameter and no output schema or annotations, the description should provide more context on the live stream state, label semantics, and effect. It fails to fully inform an agent for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the 'label' parameter beyond its type. No examples, allowed values, or context are given for what constitutes a valid label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (annotate) and resource (live stream) with a specific output (labeled event marker). It is distinct from sibling tools like 'record' or 'stream_summary', though it does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description only states the function without context on preconditions, use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the live stream for N seconds to a file (npz/csv/edf).
| Name | Required | Description | Default |
|---|---|---|---|
| fmt | No | ||
| path | No | session.npz | |
| seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden, but it only states the basic action. It does not disclose file overwrite behavior, whether recording is blocking or async, or what happens if parameters are invalid (e.g., seconds=0).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the verb and key resource ('Record the live stream'), no extraneous words, and clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's complexity is moderate (3 parameters, no output schema). The description covers the main action but omits important context like error handling, file overwrite behavior, and return value. It is minimally adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must add value. It explains 'fmt' with formats (npz/csv/edf) and mentions 'seconds' and 'file'; however, it does not detail the 'path' parameter or constraints on 'fmt' values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a live stream for a specified duration to a file with specific formats (npz/csv/edf). It is distinct from siblings like 'connect' or 'calibrate', though the stream type (e.g., EEG) is implied rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Missing prerequisites (e.g., must be connected to a device) and conditions like when recording might fail or should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Begin a neurofeedback session rewarding time spent above a metric target.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | focus | |
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only mentions rewarding time above a target, but does not describe side effects, if it stops existing sessions, or requirements like prior calibration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence front-loading the action. However, it omits important details that could be added without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a session-starting tool with no output schema and two parameters, the description lacks essential context: how to end the session, what happens during it, and return value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only vaguely references 'metric' and 'target' without explaining valid values, units, or how they affect the session.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Begin') and resource ('neurofeedback session'), and clarifies the session's function ('rewarding time spent above a metric target'). It distinguishes from sibling tools like calibrate or connect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., connection, calibration) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current brain-state snapshot. (The seconds window for rolling stats arrives in a
later phase; this currently returns the live reading.)
| Name | Required | Description | Default |
|---|---|---|---|
| seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It honestly discloses that the `seconds` window is not yet functional and that the tool returns a live reading. This is good but does not cover other behavioral aspects like whether it is read-only or requires authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The key information (snapshot, live reading, future seconds) is front-loaded. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description explains the current behavior and the future intent of the parameter. However, it lacks details on the output format or what a 'brain-state snapshot' constitutes, which may be insufficient for an agent to fully understand the tool's return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description indirectly explains the `seconds` parameter by stating it is intended for rolling stats in a future phase. This adds context beyond the schema, though it does not fully describe the parameter's current behavior or valid range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it returns a 'current brain-state snapshot' and 'live reading', which clearly identifies the tool's purpose. However, it does not explicitly distinguish from sibling tools like 'get_brain_state', though the snapshot term implies a different level of detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The note about the `seconds` parameter being for a future phase implies that for rolling stats one should wait, but no alternative tool is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0calibrateconnectdisconnectget_band_powersget_brain_stateget_neurofeedback_scoreget_signal_qualitylist_devicesmark_eventrecordstart_neurofeedbackstream_summaryScored across 12 tools
Each tool has a distinct purpose: connection management, data retrieval, recording, neurofeedback control, and event marking. While get_brain_state and stream_summary both provide state snapshots, their descriptions clarify that get_brain_state is detailed and stream_summary is a rolling snapshot, ensuring clear differentiation.
All tool names follow a consistent pattern: lowercase with underscores, using verbs like 'get_', 'list_', 'start_', 'record', etc. There is no mixing of conventions, making it easy to predict tool names.
With 12 tools, the server covers the essential BCI operations—device connection, data streaming, recording, neurofeedback, and calibration—without being overwhelming or sparse. This is a well-scoped set for a BCI server.
The tool set covers core workflows: connect/disconnect, calibrate, retrieve various brain metrics, record, mark events, and start neurofeedback. However, it lacks explicit stop operations for recording and neurofeedback, which could be a minor gap. Overall, it is largely complete for the stated domain.
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Cross-device AI memory with encrypted activity capture and context handoff between AI tools
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
NeuralBrain MCP Server - RAG, Vector Memory, LLM Routing, Agent Identity, x402 Payments
