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.
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.