Xentropy MCP Server

Status: Phase 4 — packaging & DX. Read-only semantic search shipped; write tools live.

The Xentropy MCP server exposes your Wall notes to any Model Context Protocol (MCP) client. Connect Claude Code, Cursor, or any MCP-compatible tool to search, read, and manage your notes.

#Quick Start

The fastest way to connect. One command from your terminal:

# Install globally
npm install -g @xentropy/mcp

# Authenticate (interactive — enters email + password once)
xen-notes-mcp login

# Connect to Claude Code
claude mcp add xentropy-notes -- node $(which xen-notes-mcp)

# Or: point to a remote API
XEN_API_URL=https://your-api.example.com/api claude mcp add xentropy-notes -- node $(which xen-notes-mcp)

That's it. Claude Code now has access to your Wall notes. Try asking:

"Search my notes for anything about project planning"

"List my recent notes"

"What did I capture about the API design yesterday?"

#Authentication

The MCP server authenticates through the Xentropy API. There are two paths:

#Interactive Login (Recommended)

Run once, works forever — stores a session that auto-refreshes:

xen-notes-mcp login
# Prompts: Email + Password (password hidden)

The session is stored at ~/.config/xentropy-mcp/session.json (mode 0600) and the access token is automatically refreshed before it expires.

#Static Token (CI/CD / Headless)

# Obtain a static token (one-time)
xen-notes-mcp login --email you@example.com --password '...' --show-token

# Use the token and its refresh token as environment variables
export XEN_API_TOKEN="eyJ..."
export XEN_REFRESH_TOKEN="abc123..."
claude mcp add xentropy-notes \
  --env XEN_API_TOKEN="$XEN_API_TOKEN" \
  --env XEN_REFRESH_TOKEN="$XEN_REFRESH_TOKEN" \
  -- node $(which xen-notes-mcp)

#Tools Reference

The server exposes 10 tools. All reads are scoped to your account.

#Read Tools

| Tool | Arguments | Description | |------|-----------|-------------| | ping | — | Health check — confirms the connection is live | | search_notes | query (required), limit? | Semantic search across your notes. Returns id, title, snippet, similarity score. Pro-gated. | | list_notes | folder?, type?, query?, archived?, limit? | List notes newest-first with optional filters | | get_note | id (required) | Full note — body/transcript, AI summary, and tags | | get_related_notes | id (required), limit? | Notes semantically closest to the given note | | list_folders | — | All your folders (directories) |

#Write Tools

| Tool | Arguments | Description | |------|-----------|-------------| | create_note | body (required), title?, folder? | Create a new note. Filing into a directory with a format prompt auto-formats it. | | update_note | id (required), title?, body?, folder? | Update a note — omit fields to leave them unchanged | | create_directory | name (required), parent?, formatInstructions?, icon? | Create a folder with optional AI formatting prompt | | update_directory | id (required), name?, parent?, formatInstructions?, icon? | Update a folder's properties |

#Folder References

For the folder/parent parameters, pass a directory id, or one of these keywords to target the root: unfiled, root, none, top, or an empty string.

#Error Messages

The server returns actionable errors designed for AI assistants:

| Scenario | Message | |----------|---------| | Not logged in | Not logged in. Run: xen-notes-mcp login | | Session expired | Session expired. Run: xen-notes-mcp login | | Plan-gated feature | Not available on your current plan — <reason> | | Not found | Not found — check the id and try again. | | API unreachable | Can't reach the Xentropy API — check it's running and XEN_API_URL is correct. |

#Claude Code

#Setup

# From the repo root
cd apps/mcp
npm run build          # tsc → dist/
npm run login          # authenticate once
npm run setup          # prints the exact `claude mcp add` command

# Or from anywhere after global install:
npm install -g @xentropy/mcp
xen-notes-mcp login
claude mcp add xentropy-notes -- node $(which xen-notes-mcp)

#.mcp.json (Per-Project Config)

{
  "mcpServers": {
    "xentropy-notes": {
      "command": "node",
      "args": ["/absolute/path/to/apps/mcp/dist/index.js"],
      "env": {
        "XEN_API_URL": "http://localhost:3001/api"
      }
    }
  }
}

Place this in your project root and Claude Code picks it up automatically.

#Example Workflow

#Cursor

Cursor supports MCP servers in its Features settings. Add the Xentropy server:

1. Open Cursor Settings → Features → MCP Servers
2. Click + Add new MCP server
3. Fill in:

| Field | Value | |-------|-------| | Name | Xentropy Notes | | Type | command | | Command | node /path/to/apps/mcp/dist/index.js |

4. Add env variables: XEN_API_URL (your API endpoint)
5. Click Save

After setup, Cursor's AI can call search_notes, list_notes, get_note, and all other tools directly.

#Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | XEN_API_URL | No | http://localhost:3001/api | API base URL — must include the /api prefix | | XEN_API_TOKEN | No | — | Static JWT for headless auth (A1 milestone) | | XEN_REFRESH_TOKEN | No | — | Refresh token for auto-rotation (A1 milestone) |

No Supabase variables needed — authentication goes through the Xentropy API.

#Troubleshooting

"Not logged in" / "Session expired" : Run xen-notes-mcp login (or npm run login from the repo).

"Can't reach the Xentropy API" : The API isn't running, or XEN_API_URL is wrong. Make sure it includes /api (e.g., http://localhost:3001/api).

"Not available on your current plan" : search_notes requires a Pro plan. Other tools work on all plans.

Tools don't appear in Claude Code : Check the path points to dist/index.js (built output), not src/index.ts (source). Run npm run build first.

search_notes returns no results : Semantic search uses pgvector embeddings. Make sure your API has the pgvector extension enabled and notes are indexed.

#Next Steps

• API Authentication — understand how the API auth works
• Content API — what the MCP server calls under the hood
• Changelog — latest features and fixes