AI agents

Notedog MCP server

Connect an AI agent — Claude, ChatGPT, Gemini, or any Model Context Protocol client — to your journal. There are two ways, depending on the agent:

Remote (OAuth) — for cloud assistants like Claude.ai and ChatGPT (and Claude Code over HTTP). They connect to your phone’s built-in /mcp endpoint over the tunnel, and you approve access with a tap — no install, no API key.
Local (stdio + key) — for command-line agents you run yourself (Claude Code/Desktop, Codex, Gemini, …), including over your LAN. A tiny @notedog/mcp process the agent launches, holding your API key in its own environment.

Remote MCP (OAuth)

Your phone serves a built-in MCP endpoint at https://<your-subdomain>.t.notedog.run/mcp. A cloud assistant connects to that URL, and you approve it with a tap in Notedog (an OAuth consent) — nothing to install, and no API key to copy. The agent gets its own revocable, scoped grant.

Needs the tunnel — a paid feature. Cloud assistants reach your phone over its public *.t.notedog.run address, which has the real TLS certificate they require. Turn on On the internet (tunnel) first (see remote access). LAN and Tailscale use a self-signed certificate these clients reject — use the local server below for those.

Claude.ai (web)

Open Settings → Connectors and choose Add custom connector.
Paste https://<your-subdomain>.t.notedog.run/mcp and add it.
Click Connect; a consent appears in Notedog on your phone — tap Allow (read, or read-write).
Turn it on in a chat from the + menu. On Team/Enterprise an admin adds it under organization settings.

ChatGPT

Requires developer mode, whose availability varies by ChatGPT plan — see OpenAI’s guide.

Settings → Apps → Advanced — turn on Developer mode.
Settings → Apps → Create app.
Enter a name and the URL https://<your-subdomain>.t.notedog.run/mcp; set authentication to OAuth.
Click Scan Tools, approve the consent in Notedog, then Create.
Use it from the + / tools menu in a chat. (Added tools later? Hit Refresh on the app.)

Claude Code (HTTP)

claude mcp add --transport http notedog \
  https://<your-subdomain>.t.notedog.run/mcp

Run /mcp in a session and finish the browser OAuth flow (approve in Notedog). Add --scope user to use it in every project.

Tools & access

The remote endpoint exposes the core journal tools — search_entries, get_entry, and list_entries with any grant, plus create_entry, update_entry, and delete_entry read-write. You choose read or read-write when you approve the consent, and scope is enforced on the phone. New tools appear when the assistant next reconnects (in ChatGPT, hit Refresh).

Local MCP server (stdio)

@notedog/mcp is a small Model Context Protocol server an agent launches as a local process. It holds your API key in its own environment and talks to the on-device journal API — the key never enters the model’s conversation. Best for command-line agents you run yourself, including over your LAN. Read-only by default; read-write if you mint a write-scoped key.

1. Mint a key in the app

Open the Notedog drawer → API keys → Create key, then copy it (it’s shown once). Leave Allow writes off for a read-only key, or turn it on to let the agent create, edit, and delete entries. Revoke any key from the same screen.

2. Pick a base URL

Tunnel (recommended) — https://<your-subdomain>.t.notedog.run. Real TLS, works anywhere. (See remote access.)
LAN — https://<phone-ip>:<port>, same Wi-Fi only. Set NOTEDOG_INSECURE_TLS=1 so the server accepts the phone’s self-signed certificate.

3. Register with your agent

It’s a standard stdio MCP server, so every client runs the same command — npx -y @notedog/mcp — with two environment variables: NOTEDOG_BASE_URL and NOTEDOG_API_KEY (add NOTEDOG_INSECURE_TLS=1 for a LAN address). Only where you put them differs.

Claude

With the Claude CLI:

claude mcp add notedog -s user \
  -e NOTEDOG_BASE_URL=https://<your-subdomain>.t.notedog.run \
  -e NOTEDOG_API_KEY=<paste-key> \
  -- npx -y @notedog/mcp

Check it with /mcp in a session, or claude mcp list.

Or write the JSON yourself — Claude Code reads a project .mcp.json, and Claude Desktop its claude_desktop_config.json; both use the same mcpServers shape:

{
  "mcpServers": {
    "notedog": {
      "command": "npx",
      "args": ["-y", "@notedog/mcp"],
      "env": {
        "NOTEDOG_BASE_URL": "https://<your-subdomain>.t.notedog.run",
        "NOTEDOG_API_KEY": "${NOTEDOG_API_KEY}"
      }
    }
  }
}

In a committed .mcp.json, reference an env var (as above) rather than pasting the key into the repo.

Codex

Add an entry to ~/.codex/config.toml:

[mcp_servers.notedog]
command = "npx"
args = ["-y", "@notedog/mcp"]
env = { NOTEDOG_BASE_URL = "https://<your-subdomain>.t.notedog.run", NOTEDOG_API_KEY = "<paste-key>" }

Gemini

Add to ~/.gemini/settings.json (or a project .gemini/settings.json):

{
  "mcpServers": {
    "notedog": {
      "command": "npx",
      "args": ["-y", "@notedog/mcp"],
      "env": {
        "NOTEDOG_BASE_URL": "https://<your-subdomain>.t.notedog.run",
        "NOTEDOG_API_KEY": "<paste-key>"
      }
    }
  }
}

Pi

Pi deliberately doesn’t load MCP servers — it favours small CLI tools it calls from bash. So the idiomatic way to give Pi your journal is the REST API directly: put the key in its environment and let it call the endpoints with curl.

export NOTEDOG_BASE_URL=https://<your-subdomain>.t.notedog.run
export NOTEDOG_KEY=<paste-key>

# Pi can then read — and, with a read-write key, write — via curl, e.g.:
curl -H "Authorization: Bearer $NOTEDOG_KEY" \
  "$NOTEDOG_BASE_URL/api/v2/entries?q=design"

A short skill or note telling Pi the two env vars and linking the API reference is enough for it to discover the endpoints. If you’d rather reuse the MCP server itself, a bridge such as mcporter can expose @notedog/mcp’s tools over a CLI that Pi calls from bash.

Other MCP clients

Cursor, Windsurf, Cline, and most others take the same three pieces — command npx, args ["-y", "@notedog/mcp"], and the two env vars — in their own MCP-server config. Point any MCP-compatible client at that and you’re set.

Then just ask in a session, e.g. “search my journal for the tunnel bug and summarize it.”

Don’t commit the key. Prefer a user-level config (or an env-var reference) over a shared project file, so the key never lands in a repo.

Tools

Read — available with any key:

Tool	What it does
`search_entries`	Search entries (newest first); omit the query to list recent. Paginated.
`get_entry`	Full content of one entry by path.
`list_directory`	List a folder (subfolders + entries); omit the path for the root.
`recent_entries`	Recently opened entries.
`journal_info`	Active journal name + metadata.

Write read-write key — a read-only key gets a clear 403:

Tool	What it does
`create_entry`	Create a new entry (auto-named if no path given).
`append_to_entry`	Append text to an existing entry, keeping its current content.
`update_entry`	Overwrite an entry’s whole content. Destructive — needs `confirm: true`.
`delete_entry`	Delete an entry. Destructive — needs `confirm: true`.

On a Git-backed journal, each write lands as its own commit (with the key’s name in the message), so an agent’s changes are easy to review and revert.

Updating

MCP tools are read once, when a session starts — so after updating, start a fresh session to pick up new tools.

npx setup (above) — npx pulls the latest published version, so a fresh session is usually enough. To force it: npx -y @notedog/mcp@latest (or npx clear-npx-cache); pin a version with @notedog/mcp@<version>.
Global install — npm i -g @notedog/mcp@latest.

Safety

The key lives in the MCP process’s environment and is sent as a bearer token — it never enters the model’s context.
Read-only is the default; mint a separate read-write key only when you want the agent to make changes, and revoke it when you’re done.
Destructive tools (update_entry, delete_entry) require an explicit confirm, and scope is enforced on the phone — a read-only key can’t write no matter what.

Want the raw HTTP underneath the tools? See the API reference.