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, tasks, meeting notes and people directory directly — create a note, update a task's status, add a meeting attendee — 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`
`meeting_list`	List / search meeting notes	`query`, `status`, `limit`
`meeting_get`	Get a meeting note + people + links	`id`
`meeting_create`	Create a meeting note	`title?`, `content?`, `status?`, `start_at?`
`meeting_update`	Update a meeting note	`id` + any field
`meeting_delete`	Delete a meeting note	`id`
`contact_list`	List / search people	`query`, `limit`
`contact_get`	Get a person + meetings + links	`id`
`contact_create`	Create a person	`display_name`, `email?`, `company?`
`contact_update`	Update a person	`id` + any field
`contact_delete`	Delete a person	`id`

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

More meeting tools: meeting_create_from_calendar, meeting_link_contact / meeting_unlink_contact, meeting_link_note / meeting_unlink_note, meeting_link_task / meeting_unlink_task.

More contact tools: contact_find_by_email, contact_comment_list / contact_comment_add / contact_comment_update / contact_comment_delete, contact_link_note / contact_unlink_note, contact_link_task / contact_unlink_task.

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.

4. Working a task end to end

A task can carry a spec: an objective, the repo it belongs to, and acceptance criteria that hold state. An agent works from the spec and ticks the criteria off with evidence — and you watch it happen on the task in the app.

Tool	What it does	Key inputs
`task_next`	Get the one task to work on next, with its spec, and claim it	`repo?`, `claim?`, `lease_minutes?`, `require_spec?`
`task_claim` / `task_release`	Take or drop an exclusive lease so two workers never collide	`id`, `lease_minutes?`, `force?`
`task_spec_get`	Read the spec, criteria states, artifacts, open question	`id`
`task_spec_set`	Write the spec	`id`, `objective?`, `repo?`, `acceptance_criteria?`, `test_scenarios?`
`task_spec_draft`	Propose a spec from a one-line description (AI)	`id?`, `title?`, `repo?`, `hint?`, `save?`
`task_criteria_check`	Mark one criterion passed / failed, with evidence	`id`, `criterion_id`, `passed`, `evidence?`
`task_artifact_add`	Attach a PR, branch, commit, CI run or preview	`id`, `kind`, `url`, `label?`
`task_report`	Comment + status + artifacts + criteria in one call	`id`, `comment?`, `status?`, `criteria?`, `artifacts?`, `release?`
`task_ask`	Stop and ask; pushes the question to your phone and parks the task	`id`, `question`
`template_list` / `task_create_from_template`	Start from a ready set of criteria (`bug`, `feature`, `refactor`, `spike`, `content`)	`key`, `title`, `repo?`

A typical loop:

task_next(repo: "my-repo")        → the task + its acceptance criteria, claimed for 60 min
  … do the work …
task_ask(id, "…")                 → only if you genuinely cannot decide; parks the task
task_report(id, comment: "…", criteria: [{criterion_id: "ac1", passed: true,
            evidence: "go test ./... passes"}], artifacts: [{kind: "pr", url: "…"}],
            status: "done", release: true)

Notes on the agent tools

Criterion ids are stable. Editing a criterion's wording keeps its pass/fail state; send it back with its id. A criterion with no id is new; one you leave out of task_spec_set is deleted.
task_next requires a spec by default. Tasks created before you started writing specs will not appear — pass require_spec: false to work the older backlog.
A lease expires. If an agent crashes, the task frees itself after lease_minutes; nothing has to clean up.
Everything an agent writes is attributed to the API key's name, and shown as an agent — never as you.
task_ask parks the task: task_next will not hand it back out until you answer, from the app or the web.
Artifact URLs must be http or https.

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.

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