@novaeo/brain-connector

A standalone Model Context Protocol (MCP) connector for the Novaeo Brain — your company's permission-aware memory. It runs as a local stdio MCP server and exposes twenty Brain tools to any MCP client (Claude Desktop, Cursor, Codex, or a generic stdio host). Every call is made over HTTPS to the Brain API, authenticated with your personal token. The token is your identity: the server resolves who you are and only ever returns what you are allowed to see.

This package is fully self-contained: no database, no workspace dependencies, and no secrets. Its only runtime dependencies are @modelcontextprotocol/sdk and zod.

Tools

| Tool | What it does | |---|---| | search_brain | Permission-filtered semantic search; returns ranked snippets with citations. | | answer_from_brain | Grounded answer to a question, with source citations. | | ask_novi | The full Novi agent loop with your permissions — plans, calls tools, returns a cited answer. | | write_brain_memory | Write a draft note into the brain under a visibility policy. | | get_me | Your identity, capabilities, and admin/review flags. | | list_visibility_policies | Visibility policies you may write to (ids for write_brain_memory / create_action_item). | | list_projects | List projects (ids for task assignment and filters). | | list_pods | List active pods (ids for task assignment and filters). | | list_directory | List people in the workspace (identity ids for owners/assignees). | | list_action_items | List action items (defaults to your own open items; rich filters, cursor pagination, server-side totals). | | get_action_item | Get one action item, including its updatedAt and your capabilities. | | create_action_item | Create an action item (full field set: priority, dates, frequency, pod, estimate, attachments, …). Returns the full created item including updatedAt. | | update_action_item | Update an action item's status or fields (optimistic concurrency via expectedUpdatedAt). | | list_task_events | Activity/event history of an action item. | | list_task_comments | List comments on an action item. | | create_task_comment | Comment on an action item (progress notes, findings). | | update_task_comment | Edit or delete one of your comments. | | create_reminder | Create a reminder that inherits its trigger message's visibility. | | summarize_thread | Summarize a chat thread into a short, cited summary. | | promote_to_curated_note | Promote a reviewed note into the curated novaeo-brain vault. |

Listing action items without miscounting

list_action_items returns one page, capped at limit (max 100). Two habits keep the results honest:

• Paginate with cursor. A non-null nextCursor in the response means more items match. Pass it back as cursor, with the same filters and sort, to get the next page — a cursor is bound to the filters that minted it, and reusing one after changing a filter is an error rather than a silently short page.
• Count with includeStats, never by counting rows. stats is a server-side aggregate over every item matching your filter (under your permissions), so it stays correct when the page is capped. Its by-status buckets — open, inProgress, blocked, completed, cancelled — sum to total. Add includeClosed: true for a breakdown across all statuses. Counting the returned rows instead reports the page cap as though it were a total.

Rows are a compact projection by default (id, itemNumber, title, status, priority, dueDate, ownerName, ownerIdentityId, lastActivityAt, updatedAt) — enough to identify, triage, and immediately update an item. Pass verbose: true for the full field set. lastActivityFrom / lastActivityTo window the set on last_activity_at, which is also the default sort key; items with no recorded activity fall outside any window. Both take an ISO date (YYYY-MM-DD) or a full ISO instant, normalized to UTC — a date-only bound covers that entire UTC day, so lastActivityTo: "2026-08-19" includes the 19th.

Unknown arguments are rejected with an MCP InvalidParams error rather than silently dropped, so a call that works around a schema gap fails loudly instead of returning correct-looking page-one data.

Two governance tools are hidden unless the connector starts with BRAIN_RULE_TIER_ENABLED=on / BRAIN_LAW_TIER_ENABLED=on: promote_to_rule and set_law (reviewer / Brain-admin enforced server-side).

Configuration

Two environment variables are required. The connector exits with a clear message if either is missing.

| Variable | Required | Description | |---|---|---| | BRAIN_API_URL | yes | Base URL of your Brain API, e.g. https://brain.novaeo.com. | | NOVAEO_BRAIN_TOKEN | yes | Your personal Brain token (starts with nbk_). Sent as Authorization: Bearer <token>. |

Getting your token

Your Brain token is issued from the Connect-your-agent page in the Novaeo app (coming soon). It looks like nbk_.... Treat it like a password — it grants exactly your access. Do not commit it; pass it via your MCP client's environment block.

Usage

Run directly with npx (no install needed):

BRAIN_API_URL=https://brain.novaeo.com \
NOVAEO_BRAIN_TOKEN=nbk_your_token \
npx @novaeo/brain-connector

The process speaks the MCP protocol over stdio; diagnostics go to stderr.

MCP client configuration

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "novaeo-brain": {
      "command": "npx",
      "args": ["-y", "@novaeo/brain-connector"],
      "env": {
        "BRAIN_API_URL": "https://brain.novaeo.com",
        "NOVAEO_BRAIN_TOKEN": "nbk_your_token"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "novaeo-brain": {
      "command": "npx",
      "args": ["-y", "@novaeo/brain-connector"],
      "env": {
        "BRAIN_API_URL": "https://brain.novaeo.com",
        "NOVAEO_BRAIN_TOKEN": "nbk_your_token"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.novaeo-brain]
command = "npx"
args = ["-y", "@novaeo/brain-connector"]
env = { BRAIN_API_URL = "https://brain.novaeo.com", NOVAEO_BRAIN_TOKEN = "nbk_your_token" }

Generic stdio MCP client

Any MCP host that launches a command can use:

{
  "command": "npx",
  "args": ["-y", "@novaeo/brain-connector"],
  "env": {
    "BRAIN_API_URL": "https://brain.novaeo.com",
    "NOVAEO_BRAIN_TOKEN": "nbk_your_token"
  }
}

License

MIT