Skip to content

MCP tools reference

Reference for every tool the Plavn MCP server offers: what it does, its inputs, its limits and what it returns.

An assistant picks these tools by itself from your questions. This page is for knowing what each can and cannot do. All results are JSON text. All of them work on your account only.

Tool Access
list_tasks · list_customer_reports · search_mail · get_email_thread · search_knowledge Read and write tokens
create_task · complete_task · prepare_reply Read and write tokens only

Tasks from your planner. Archived and deleted tasks are not included.

Input Meaning
filter today (due today, plus recurring tasks due today and not done yet), overdue, open (everything not done, soonest due first; recurring tasks have no due date) or done (completed in the last 7 days). Default open.
project Only tasks of a project whose name contains this text.
limit 1 to 100. Default 30.

Returns, for each task: id, title, status, priority, due, project, githubIssue (link) and fromEmail (the subject of the email it came from). Recurring tasks due today come back with recurring: true and dueDay. A recurring task is never overdue. Recurring tasks are added to today only when you do not filter by project.

Work emails that Plavn turned into tasks, for questions like “what bugs did customers report this week?”. See Tasks from email.

Input Meaning
days 1 to 90. Default 7.

Returns up to 50 reports, newest first: the email (emailId, from, subject, receivedAt), the task (taskId, task, status), the analysis (cut to 1,500 characters), confidence (high, medium, low or null), the suspectCommits (repo, short sha, first line of the message, url, why), the GitHub issue and its state, and customerTold: the state of the “it’s done” reply to the sender (such as ready or sent), or null. Suspect commits need GitHub connected.

Searches your received mail, across all your accounts. Spam and Trash are left out unless you ask for them with in:spam or in:trash.

Input Meaning
query Up to 500 characters: words, or operators from:, to:, subject:, has:attachment, after:YYYY-MM-DD, before:YYYY-MM-DD and in:needs-reply. The other in: places of mail search (unread, starred, snoozed, spam, trash) are accepted too.

Returns up to 20 matches, followed by mail about the same thing that does not contain your words (related: true). Each has id, from, subject, date, needsReply and a 300-character snippet. Use id with get_email_thread or prepare_reply.

Input Meaning
emailId The id of an email, from search_mail.

Returns the conversation around that email, oldest first: up to 30 received and 30 sent messages, each with direction (received or sent), from, to, subject, date and text, as plain text of up to 4,000 characters without the quoted earlier messages.

Searches by meaning across your tasks, projects and sent mail (including the copy of your Sent folder). It does not search received mail; use search_mail for that. See What Plavn keeps.

Input Meaning
query 2 to 1,000 characters.
limit 1 to 20. Default 8.

Returns pieces of text with their type (task, project, sent_email or sent_history), id, a similarity score and the content. It only returns what Plavn has indexed, so it can be empty if Prepare replies and tasks is off.

Needs a write token. Adds a task to your Inbox, or to a project.

Input Meaning
title Required, up to 300 characters.
due YYYY-MM-DD for a whole day (due at the end of it), or YYYY-MM-DDTHH:mm in your time zone. A value with a time-zone offset is taken as it is.
project The name, or part of it, of one of your projects. If nothing matches, the task is not created and the assistant is told.
priority URGENT, HIGH, MEDIUM, LOW or NONE. Default NONE.
notes Up to 10,000 characters.

Returns the new task’s id, title, due and project (Inbox when none). It appears in Plavn on all your devices.

Needs a write token.

Input Meaning
taskId The id of a task, from list_tasks.

Marks the task done. A recurring task is marked done for today (your current day, in your time zone) and is open again on its next due day; if it is not due today, the call is refused. Completing a task through MCP does not show the “also close the GitHub issue?” or “send the reply you prepared?” prompts that the app shows. See Tasks from email.

Needs a write token. Asks Plavn to prepare a reply, and a task for work mail, for an email.

Input Meaning
emailId The id of a received email.

Returns status: "preparing". The reply appears in Plavn shortly, as a draft for you to review and send; nothing is sent. It is the same as Prepare a reply in the app (see Review and send), and it follows the same rules. The tool tells the assistant why it refused when:

  • the mail was sent automatically (a no-reply address, a mailing list or an automatic reply),
  • the email account has AI turned off in Plavn,
  • you have reached this month’s AI allowance (your own AI key is never limited),
  • the id is not one of your emails.