Troubleshooting
Most problems come down to one of three things: authentication, the Pro gate, or an account that hasn't synced any data yet. Work through these before reaching out.
Connection & auth errors
The endpoint is https://mcp.penlog.app (JSON-RPC 2.0 over
Streamable HTTP). Clients that support the interactive flow should use
one-click OAuth; others connect with a
plg_live_ bearer token (see
remote MCP clients).
| Status | Cause | Fix |
|---|---|---|
401 | Token missing, invalid, or revoked | Re-mint a token in Settings → API tokens and send it as Authorization: Bearer plg_live_… |
402 | Account isn't on Penlog Pro | The MCP API requires Pro. Subscribe in the app; the entitlement applies on the next call — no need to re-mint. |
403 | Token scope too narrow for the tool | Re-mint with a wider preset (Read + Seed, or Full). For example, update_task needs write scope. |
"Subscription required" / 402 on every call
The MCP API is a Pro feature. If tools/list
succeeds but every tools/call returns 402, the
account behind the token isn't Pro. Subscribe in the app (Settings → Penlog
Pro); the entitlement is picked up on the next request.
Tools connect but return nothing
Penlog pages live on your iPad and sync to the cloud on Pro. A brand-new account, or one whose pages haven't synced, returns empty results:
list_pagesempty → no pages have synced yet. Open the app, confirm you're signed in and on Pro, write or open a page, and let it sync.list_tasksempty → tasks appear once they're written on a page (a bullet line) or pulled from a connected Notion tasks database.get_page"not found" → thepage_idmust come fromlist_pagesor a search result and belong to your account.
Notion tasks aren't syncing
Two-way Notion sync requires connecting Notion in the app (Settings →
connectors). create_task_seed pushes a new task to your Notion
tasks database only when Notion is connected; without it, the task still lands
on the page but won't appear in Notion.
Moving Notion to a different workspace
You can move Penlog to another Notion workspace and keep your history, as
long as you bring the databases with you. Duplicate or move the page holding
your Penlog Journal and Tasks databases
into the new workspace, then reconnect Notion in the app and share that page
with Penlog. Every row carries a Penlog ID, so the next sync
matches your tasks and journal entries back up, in place. Nothing is created
twice, and nothing in Notion is deleted.
Start from a fresh copy of the template instead and there is nothing to match against: the new databases fill up from that day forward, and your earlier days stay in the old workspace. One thing Penlog won't guess at is a date that already has two journal rows for the same day. It leaves those alone rather than risk writing over the wrong one.
search / fetch vs search_pages / get_page
tools/list returns eight tools: six core tools plus
search and fetch, which are
ChatGPT-compatible aliases of search_pages and
get_page. search / fetch return
citation-shaped results ({ id, title, url, text }); the core tools return
richer structured data (snippets, reconciled task status, structured lines).
Use whichever your client expects.
Tokens are shown once
A plg_live_ token is displayed only at creation — you can't
retrieve it afterward, only revoke and re-mint from
Settings → API tokens. Revocation is immediate.
Still stuck?
Email support@penlog.app with your client, the tool you called, and the error. The tool reference lists every error code.