MCP server

Emanote can expose an MCP (Model Context Protocol) endpoint beside its live server, so that Claude Code, Codex, or any other MCP-aware client can query your notebook directly from the same process that renders it.

Enable it by passing --mcp-port PORT to emanote run:

emanote run --port 9010 --mcp-port 8079

Emanote prints one line to stderr once the MCP endpoint is ready:

[mcp] listening on http://localhost:8079/mcp

Client setup

Claude Code

Claude Code reads MCP server configuration from .mcp.json in your project root (or your home directory). Point it at the running Emanote:

{
  "mcpServers": {
    "emanote": {
      "url": "http://localhost:8079/mcp"
    }
  }
}

Start Emanote in one terminal (emanote run --mcp-port 8079), launch Claude Code in the same directory, and it will connect on startup. Use /mcp inside Claude Code to verify the server appears and list its resources.

Codex

Codex uses ~/.codex/config.toml for MCP servers. HTTP transport wiring looks like:

[mcp_servers.emanote]
url = "http://localhost:8079/mcp"

Restart Codex after editing the config; it will pick up the server on next launch.

Quick sanity check with curl

MCP is JSON-RPC over HTTP with SSE responses. A raw initialize call:

curl -sS -N -X POST http://localhost:8079/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

You should see an SSE event: message frame carrying the server’s implementation metadata and advertised capabilities.

Resources

Emanote advertises the notebook under the emanote:// scheme as a single static export:

resources/list returns only the metadata export. Emanote intentionally does not enumerate one entry per note: that scales linearly with notebook size and inflates context on every poll. Clients discover note paths from emanote://export/metadata (every note’s filePath) and the query tools below; the underlying files are read through the client’s own filesystem tools (e.g. Claude Code’s Read, Codex’s local file access), not through MCP.

Algorithmic complexity

Per-request cost, where N = number of notes in the model and R = total resolved relations (wikilinks + transclusions) across all notes:

Reads are uncached: every resources/read re-runs against the live model. Phase 4 (subscriptions) replaces polling with push notifications and removes the per-poll cost for clients that opt in.

Tools

Emanote advertises three read-only query tools through MCP’s tools/list. They share the live model snapshot used by resources and return JSON-encoded text payloads.

Each path returned is a notebook-relative source path (e.g. guide/mcp.md) — feed it to the client’s own filesystem read tool to load the body. resolve_wikilink is the structured equivalent of asking Emanote what [[…]] would resolve to from the current note, including ambiguity disambiguation by closest common ancestor.

Errors surface in two ways: malformed input that can’t be parsed (unknown path, empty wikilink) comes back as a text result with isError: true; a missing required argument comes back as JSON-RPC error -32602 per the MCP protocol.

Debugging

• Pass -v / --verbose to Emanote and the underlying mcp library will print one [request] / [response] line per JSON-RPC call to stdout. Useful when a client is misbehaving or you want to see exactly what a tool call looks like.
• If MCP fails to bind (port already in use, privileged port without capability), Emanote exits with the socket exception — MCP and the live server share process lifetime, so neither runs when the other can’t start.
• MCP is not enabled unless --mcp-port is present under the run subcommand. emanote gen never starts MCP.

Authentication

There is none today. The server is intended for local use, bound to a loopback port. Do not expose the MCP port to the public internet or to an untrusted network.