MCP / API

Planist ships a hosted MCP server (Model Context Protocol). Once connected, an MCP client like Claude Code can read and write your notes and tasks directly — create a note, update a task's status, add a comment — all as you, authenticated by a personal API key.

Endpoint: https://planistai.com/api/mcp (Streamable HTTP)
Auth: a personal API key sent as Authorization: Bearer plnst_…
Acts as you: every tool runs as the user who owns the key. A key can never touch another user's data.

1. Create an API key

Open Settings → API Keys.
Click Create key, give it a name (e.g. "Claude Code").
Copy the key now — it's shown only once. It looks like plnst_….

You can revoke a key anytime from the same screen; revoked keys stop working immediately.

2. Connect Claude Code

Run this in your terminal, replacing plnst_YOUR_KEY with the key you just copied:

claude mcp add --transport http planist https://planistai.com/api/mcp \
  --header "Authorization: Bearer plnst_YOUR_KEY"

Then in Claude Code, ask it to do something — e.g. "List my overdue tasks" or "Create a note titled Groceries with a checklist".

Other MCP clients

Any client that supports a remote (Streamable HTTP) MCP server works. Point it at the endpoint with the Authorization header. Example config block:

{
  "mcpServers": {
    "planist": {
      "type": "http",
      "url": "https://planistai.com/api/mcp",
      "headers": { "Authorization": "Bearer plnst_YOUR_KEY" }
    }
  }
}

3. Available tools

Tool	What it does	Key inputs
`note_list`	List / search your notes	`query`, `limit`
`note_get`	Get a note's full markdown	`id`
`note_create`	Create a note from markdown	`content`, `title?`
`note_update`	Replace a note's body / title	`id`, `content`, `title?`
`note_add_image`	Upload & append an image to a note	`id`, `image_base64`, `filename?`, `mime?`
`task_list`	List / filter your tasks	`query`, `status`, `limit`
`task_get`	Get a task's details	`id`
`task_create`	Create a task	`title`, `description?`, `priority?`, `category?`, `remind_at?`, `tags?`
`task_update`	Update task fields	`id` + any field
`task_set_status`	Change status	`id`, `status` (`todo` / `in_progress` / `done`)
`task_comment_list/add/update/delete`	Manage task comments	`task_id` / `comment_id`, `content`

More note tools: note_delete, note_set_tags, note_pin, note_share / note_unshare, note_toggle_checklist, note_set_timeline, note_comment_add / note_comment_list, note_analyze (AI), note_materialize_tasks (turn extracted tasks into real ones).

More task tools: task_delete, task_set_tags, task_set_subtasks, task_share / task_unshare, task_analyze (AI).

Calendar: calendar_agenda (tasks by date range), gcal_status, gcal_create_event (push to Google Calendar — requires Google connected in the app).

Productivity & AI: search (notes + tasks), get_stats, get_tags, focus_log, focus_stats, ai_chat (the assistant), daily_summary.

Notes on behavior

note_update / note_create write plain markdown (GFM tables and - [ ] checklists render). This resets a note's rich-editor blocks (callouts, toggles) to markdown.
note_add_image preserves existing rich content and appends the image. Images are limited to 5 MB.
remind_at accepts ISO-8601 (e.g. 2026-06-25T09:00:00Z) or a plain date (2026-06-25).
The MCP connector is a Premium feature — free accounts can't connect.
AI tools (note_analyze, task_analyze, ai_chat, daily_summary) use your monthly AI quota.
Reads are paged; limit caps at 50.

4. Security

Keys are stored hashed (SHA-256). The full key is shown only at creation and never again.
Each key resolves to exactly one user; tools are bound to that user, so cross-account access is impossible.
Hidden / PIN-protected notes are not accessible via MCP — there's no PIN session over the API.
Revoke a key the moment it might be exposed; it stops working instantly.

Troubleshooting

401 unauthorized — the key is wrong, revoked, or the Authorization header is missing/misformatted. It must be Bearer plnst_….
"note is protected by a PIN" — you're targeting a hidden note; those are off-limits to the API by design.