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 |
list_tasks
Section titled “list_tasks”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.
list_customer_reports
Section titled “list_customer_reports”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.
search_mail
Section titled “search_mail”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.
get_email_thread
Section titled “get_email_thread”| 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.
search_knowledge
Section titled “search_knowledge”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.
create_task
Section titled “create_task”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.
complete_task
Section titled “complete_task”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.
prepare_reply
Section titled “prepare_reply”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.