MCP tool reference

Penlog exposes six core tools over MCP at mcp.penlog.app, spoken as JSON-RPC 2.0 over Streamable HTTP (POST only). Tools are invoked with tools/call, passing the tool name and an arguments object. (Two more — search and fetch — exist for ChatGPT compatibility.)

Calling convention

Each tool's result payload is JSON-encoded into a single MCP text content block. Decode result.content[0].text to get the objects documented below.

// tools/call request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_pages",
    "arguments": { "limit": 5 }
  }
}

// result — the payload is JSON-encoded into a single text content block
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\"pages\":[ ... ]}" }
    ]
  }
}

Authentication & scopes

Connecting requires Penlog Pro. Authenticate with one-click OAuth or a plg_live_ bearer token (see Quickstart and Remote MCP clients). Tokens carry one of three scope presets; each tool declares the scope it needs:

Rate limits are per token: 60 requests/minute and 1000 requests/hour.

{ "from": "2026-06-01", "to": "2026-06-19", "limit": 50 }

{
  "pages": [
    { "page_id": "0f9e…", "date": "2026-06-19", "has_ink": true, "has_ocr": true },
    { "page_id": "1a2b…", "date": "2026-06-18", "has_ink": true, "has_ocr": true }
  ]
}

{ "page_id": "0f9e8d7c-1234-…" }

{
  "page_id": "0f9e8d7c-1234-…",
  "date": "2026-06-19",
  "has_ink": true,
  "ocr_text": "Follow up on API spec\nTeam sync notes",
  "ocr_markdown": "- [ ] Follow up on API spec\n- Team sync notes",
  "structure_json": {
    "lines": [
      {
        "line_id": "ln_3",
        "text": "Follow up on API spec",
        "section": "tasks",
        "notation": "bullet",
        "status": "done",
        "page_status": "open",
        "status_source": "reconciled",
        "completed_date": "2026-06-19",
        "notion_url": "https://www.notion.so/…"
      }
    ]
  },
  "pdf_url": "https://…(signed)",
  "png_url": "https://…(signed)",
  "signed_url_ttl_seconds": 3600
}

{ "query": "API spec", "limit": 20 }

{
  "query": "API spec",
  "results": [
    {
      "page_id": "0f9e…",
      "date": "2026-06-19",
      "snippet": "…follow up on API spec with the team…"
    }
  ]
}

{ "status": "open", "since": "2026-06-01", "limit": 50 }

{
  "tasks": [
    {
      "task_link_id": "7c3a…",
      "text": "Follow up on API spec",
      "status": "todo",
      "first_seen_date": "2026-06-16",
      "completed_date": null,
      "source_page_id": "0f9e…",
      "notion_url": "https://www.notion.so/…"
    }
  ]
}

{ "target_date": "2026-06-20", "text": "Draft the launch post", "source_url": "https://…" }

{
  "task_link_id": "9d2f…",
  "block_id": "b1c4…",
  "page_id": "44a0…",
  "created": true,
  "reused_existing_task": false,
  "notion_pushed": true,
  "notion_task_id": "20e1…",
  "notion_url": "https://www.notion.so/…"
}

{ "task_link_id": "7c3a…", "status": "done" }

{
  "updated": true,
  "status": "done",
  "text": "Follow up on API spec",
  "notion_updated": true
}

ChatGPT compatibility — search & fetch

Two extra tools, search and fetch, exist specifically for ChatGPT: it only accepts a connector that exposes both (otherwise the user must enable Developer Mode), and its Deep Research path calls only these two. They're thin read-scope aliases:

• search({ query }) → { results: [{ id, title, url }] } — searches the same index as search_pages.
• fetch({ id }) → { id, title, text, url, metadata } — returns one page's OCR'd text by page_id, like get_page without the structured lines.

Both follow OpenAI's required schema (the result carries a structuredContent object). If you're authoring against Penlog directly, prefer search_pages + get_page — they return richer data (snippets, structured lines, reconciled task status).

Errors

Failures return a JSON-RPC error with an HTTP status to match. Common ones: