Skip to content
Datanotes

Connect agents

Agents reach Datanotes through datanotes-mcp, an MCP server kept apart from the engine. It offers every operation as a tool, plus the tools of the registered apps. Each call becomes a request to the engine’s HTTP API, which checks what the token may do and records who did what; the call is then reported to the engine’s change feed.

Clients reach it in one of two ways:

  • stdio: the client starts datanotes-mcp itself. Use this on your own computer.
  • HTTP: the client calls /mcp on a running datanotes-mcp serve, with a bearer token. Use this for several clients at once, and for hosted assistants that can send a custom Authorization header (the server offers no OAuth).

On your computer (stdio)

Section titled “On your computer (stdio)”

datanotes-mcp --vault <folder> uses the engine that already runs on the vault. If none runs, it starts one (datanotes serve) for as long as the client stays open. It uses the vault owner’s token (from <vault>/.datanotes/service.json), so the agent has full rights: to limit an agent, give it an app token with --url and --token-file, or over HTTP.

Claude Code

Terminal window
claude mcp add datanotes -- npx -y datanotes-mcp --vault /path/to/vault

Claude Desktop, Cursor and other clients with an mcpServers file

{
  "mcpServers": {
    "datanotes": {
      "command": "npx",
      "args": ["-y", "datanotes-mcp", "--vault", "/path/to/vault"]
    }
  }
}

On Windows, escape the backslashes in JSON and TOML (C:\\Users\\me\\MyVault); Claude Code on Windows (not WSL) needs npx through cmd: claude mcp add datanotes -- cmd /c npx -y datanotes-mcp --vault C:\Users\me\MyVault.

Codex (~/.codex/config.toml)

[mcp_servers.datanotes]
command = "npx"
args = ["-y", "datanotes-mcp", "--vault", "/path/to/vault"]

To an engine at an address instead of a local vault:

Terminal window
npx -y datanotes-mcp --url https://datanotes.example.com --token-file ~/.datanotes-token

Over HTTP

Section titled “Over HTTP”

Run the server next to the engine:

Terminal window
npx -y datanotes-mcp serve --engine http://127.0.0.1:27150 --port 27151

Clients connect to http://127.0.0.1:27151/mcp and send their own token. Claude Code:

Terminal window
claude mcp add --transport http datanotes http://127.0.0.1:27151/mcp --header "Authorization: Bearer <token>"

Clients with an mcpServers file (Cursor, Claude Code’s .mcp.json):

{
  "mcpServers": {
    "datanotes": {
      "type": "http",
      "url": "http://127.0.0.1:27151/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Give each agent or device its own app token. An app token can write only the tables you allow (write), change the schema only with ddl, and undo only with maintain; the journal records its name. Create one with the owner’s token:

Terminal window
curl -s http://127.0.0.1:27150/datanotes/apps/create/ \
  -H "Authorization: Bearer <owner token>" -H "Content-Type: application/json" \
  -d '{"name": "claude", "write": ["*"], "ddl": true, "maintain": true}'

The answer holds the token, shown once. See Apps and Security.

Logs

Section titled “Logs”

datanotes-mcp exports its logs (tool calls, refused requests, sessions; never tokens or argument values) over OTLP/HTTP when OTEL_EXPORTER_OTLP_ENDPOINT is set, to SigNoz or any OpenTelemetry collector. See Telemetry.

Who made a change

Section titled “Who made a change”

Every write records its actor: the client’s name from the MCP handshake, its session, the tool, and the credential (owner, or the app). An agent can also name its model with start_session when an app offers it (datanotes-agent does). list_migrations shows who made each change (by: client / model, and the app); list_changes shows the full actor of every change and tool call.