Notedog MCP server

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 tunnela 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)

1. Open Settings → Connectors and choose Add custom connector.
2. Paste https://<your-subdomain>.t.notedog.run/mcp and add it.
3. Click Connect; a consent appears in Notedog on your phone — tap Allow (read, or read-write).
4. 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.

1. Settings → Apps → Advanced — turn on Developer mode.
2. Settings → Apps → Create app.
3. Enter a name and the URL https://<your-subdomain>.t.notedog.run/mcp; set authentication to OAuth.
4. Click Scan Tools, approve the consent in Notedog, then Create.
5. 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 same twelve tools as the local server — list_entries, search_entries, get_entry, related_entries, changes_since, list_directory, recent_entries, and journal_info with any grant, plus create_entry, append_to_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.

Step one

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.

Step two

Pick a base URL

Step three

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 keyPrefer 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:

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

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.

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.
• Scope is enforced on the phone — a read-only key can’t write no matter what, and over OAuth the write tools simply aren’t offered to a read-only grant. Every write is its own commit, so anything an agent does is reviewable and revertible.

Want the raw HTTP underneath the tools? See the API reference. And if you want an agent that maintains index notes on a schedule, there’s a recipe for that.