Skip to content
Datanotes

Apps

Datanotes is extended by apps: programs in any language that use the HTTP API and the change feed (POST /datanotes/changes/, SSE GET /datanotes/changes/stream, webhooks created by the owner), and may add MCP tools that teach agents how to use part of the database. Agents keep one MCP address: the MCP server (datanotes-mcp) lists the apps’ tools after the engine’s operations.

  • Register (owner token): POST /datanotes/apps/create/ {"name": "planning", "write": ["personal.tasks.*"], "mcp_url": "http://127.0.0.1:5235/mcp", "mcp_token": "…"} returns the app’s token once (the engine keeps its SHA-256 in .datanotes/apps.json). Also apps/, apps/update/, apps/refresh/, apps/rotate-token/, apps/delete/.
  • App token: reads are always allowed; row writes only on tables matching write (catalog.schema.table, catalog.schema.*, catalog.*, *); schema changes only with "ddl": true; configuration, undo, restore, vacuum and rebuilding the semantic index only with "maintain": true (meant for an agent’s own token). Creating and deleting apps and webhooks, listing apps, rotating tokens and /api/ stay the owner’s; an app may list webhooks and see, refresh and update its own entry. Writes carry actor.app; an app that forwards the agent’s X-Datanotes-Actor gets both recorded (“harness / model via app”). An app may change its own mcp_url, mcp_token, description and instructions with apps/update/ (e.g. at start).
  • Tools: an app with mcp_url is an ordinary MCP server (JSON or SSE answers). The engine reads its tools/list and instructions at start, every 5 minutes, when the app is created, when its mcp_url or mcp_token change and on apps/refresh/, and holds its mcp_token. POST /datanotes/apps/tools/ lists the tools (each with its app) and the instructions; POST /datanotes/apps/call/ {"tool", "arguments"} calls one for the caller, forwarding X-Datanotes-Actor with Authorization: Bearer <mcp_token>, and answers {ok, value, servedBy} (timeouts: 15 s to open a session, 30 s to list, 180 s per call). A name already taken by an operation or by an app registered earlier is skipped (skippedTools on the app’s entry). While the app is down its tools stay listed and answer that it is not reachable. A tool may declare _meta: {"datanotes/tables": ["…"]}: describe_table then lists it under tools.
  • Tool calls are change-feed events op: "tool_call" (call: tool, args cut at 300 characters, ok, value cut at 1000, servedBy, durationMs, summary, session, resultChars, resultTokens), sent only to consumers that ask for that op. MCP servers report them with POST /datanotes/tool-calls/record/ after each call; /apps/call/ itself records nothing.