Agents and MCP

What agents and MCP are

An AI agent is an assistant such as Claude Desktop or Claude Code that can do things for you, not just chat. MCP (Model Context Protocol) is the open standard that lets an agent connect to another app and work with its data. Letos has its own MCP server built into the desktop app.

With it you can ask an agent in plain words: “What is on my plate this week?”, “Break my goal into steps”, “Which unread mail needs an answer?”. The agent reads your tasks, goals, calendar and mail in Letos and, if you allow it, creates tasks or saves a draft.

• The server runs only on your computer: it listens on 127.0.0.1 (default port 47800, path /mcp) and can’t be reached from another computer or from the internet.
• The agent works on the same local database as the app. Nothing passes through our server.
• Reading is allowed once you add an agent. Writes are off by default.
• Nothing is ever deleted, and an e-mail is sent only after you confirm it in the app.

Local MCP is in the desktop app. It isn’t on the iPhone.

Quick start: Claude Desktop and Claude Code

1. Open Settings → Agents.
2. Turn on Allow agents (MCP). The first time you see the consent Send data off this device: it says what agents will see (mail, tasks, goals, calendar, notes) and that the agent may pass it on to its provider. The server starts only after Allow.
3. Under Agents with access click Add agent. Enter a name (for example “Claude Desktop”) and choose Read, Write or Read and write. Start with Read.
4. Copy the token and the client setup that appear. You will see them only once.
5. Connect the client (below), restart it and ask something simple: “List my tasks for today.”

Letos must be running and agents must be allowed. Turning the switch off withdraws the consent and stops the server at once. The same switch is in Settings → Privacy.

Claude Code

Claude Code connects directly over HTTP. Click Copy Claude Code command and run it in a terminal:

claude mcp add --transport http letos http://127.0.0.1:47800/mcp --header "Authorization: Bearer <agent token>"

Treat the command with the token as a secret. When you issue a new token, run the command again. If you changed the port, change it in the address.

Claude Desktop

Claude Desktop runs the command letos mcp, which only forwards messages to the running app. The token goes in the variable LETOS_MCP_TOKEN. Put this in claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/) or click Copy Claude Desktop setup, which fills in the path for your computer:

{
  "mcpServers": {
    "letos": {
      "command": "/Applications/Letos.app/Contents/MacOS/letos",
      "args": ["mcp"],
      "env": { "LETOS_MCP_TOKEN": "<agent token>" }
    }
  }
}

Then restart Claude Desktop. Without LETOS_MCP_TOKEN, letos mcp uses the original shared token from the file, if one exists.

Other clients

Any MCP client that supports the HTTP transport connects to the address in Settings → Agents with the header Authorization: Bearer <agent token>.

Connecting over the internet

Coming soon Connecting over the internet is not available yet. Until the sign-in connector (OAuth) ships, use the local connection above.

Plan: agents that run in the cloud, such as Claude on the web, will reach your web account with a Plus plan or higher. There is a limited variant for it already: a cloud endpoint with its own token (it starts with lmcp_) that sees only tasks, goals and calendar. It has no mail and no search, and it is not open to everyone yet. Its limits are the same or higher than the local ones. When it is ready, this page and the Settings tab will say so.

Agents in the cloud

You can also connect an agent to Letos on the web — regardless of which computer you’re on. No app on your computer is involved: the agent connects straight to https://app.letos.app/api/mcp and authenticates with a token you create in Settings.

Cloud agents need the Plus or Unlimited plan. Free sees only an offer to change plan.

• The agent works with tasks, goals and calendar. The web has no mail, so an agent there can’t reach mail at all.
• Writes are off by default and every new token is read-only. You allow writing per token.
• Data flows between the agent and our server, not between your computer and the agent. What the agent does with it next is governed by its vendor’s terms.

Creating a token

1. Open Settings → Agents.
2. In the Access tokens section, enter a Token name (for example “Claude Code on my laptop”) and click Create token.
3. Copy the token shown — you see it only once. Letos stores only its fingerprint.
4. Paste it into the agent’s settings. For Claude Code:

claude mcp add --transport http letos https://app.letos.app/api/mcp --header "Authorization: Bearer <token>"

Token access

Each token has its own access, changeable at any time with Edit access:

Access	What it allows
Read	Only reads tasks, goals and calendar. The default for a new token.
Write	Only creates and edits (never deletes) — it cannot read: read tools are refused and hidden from this token. Pick Read and write if the agent also needs to look things up.
Read and write	Both.

Under Advanced… you can also limit a token to specific modules (Tasks, Goals, Calendar). The agent then doesn’t see the other modules at all — it can’t even call them. The change applies from the agent’s next request.

Writes additionally require the Allow writes switch. While it is off no token can write: a Read and write token then only reads, and a Write token can do nothing at all.

Revoking a token

Revoke token disconnects that agent immediately — its next request fails with 401. The list also shows when each token was created and last used, so you can spot the unused one.

If you lose a token or expose it by accident, just revoke it and create a new one.

Limits and log

Limit	Plus	Unlimited
Reads	at most 60 per minute	at most 120 per minute
Writes	at most 10 per minute and 200 per day	at most 20 per minute and 1,000 per day
Changes synced to your other devices	at most 60 per hour	at most 120 per hour

In Settings → Agents → Activity log you see every call a cloud agent made: time, client, tool and result — including refused calls. The log is kept for 30 days (at most 5,000 rows) and arguments are stored shortened, without the content of tasks or notes.

What an agent may do, limits and consents

May do

• Read tasks, goals, calendar events and mail (as text, attachments only as name, type and size).
• With write access and Allow writes switched on: create and edit tasks, finish a task, add a step to a goal, create an event on your calendar (without guests), archive or snooze a mail thread, save a draft.
• Ask to send a draft. It leaves only after you confirm.

May not do

• Delete anything, work in bulk, change settings, accounts, sync or other agents’ tokens.
• Invite guests or send anything without your confirmation.
• Change the category of a goal or the goal links of tasks.

Consents and switches

Setting	What it does
Allow agents (MCP)	Main switch and consent. Off = the server does not run, no access.
Agent permissions	Read / Write / Read and write, optionally only some of Mail, Calendar, Tasks, Goals (under Advanced…).
Allow writes	Off (default) = no agent writes, even with write permission.
Revoke / New token	Disconnects one agent at once. A new token invalidates the old one.

Limits (fixed, can’t be raised)

Limit	Value
Reads	at most 60 per minute
Writes	at most 10 per minute and 200 per 24 hours, one at a time
Changes synced to your other devices	at most 60 per hour (one write can mean several changes, for example finishing a goal step)
Sending e-mail	at most 20 per 24 hours, each only after you confirm
Request size	at most 256 KB
Items per page of results	default 25, at most 50

When an agent goes over a limit, the server answers 429 and says in how many seconds it can try again.

Sending e-mail by an agent

When an agent wants to send an e-mail, Letos shows the window Agent wants to send an e-mail with the sender, recipients, subject, the start of the message, its length and attachment names. You have 120 seconds to choose Send or Reject. With no answer, nothing is sent.

Managing agents

• Each agent has its own token and permissions. Without a valid token the server refuses every request.
• Edit changes permissions and modules from the agent’s next request. New token issues a new one and the old one stops working. Revoke disconnects the agent. Both are confirmed.
• The list shows when the agent was created and when it last connected.
• If you used agents before individual tokens existed, the old token from the file mcp/token became an agent with that name and full access.
• Tokens are 64 characters long, don’t expire and don’t sync to your other devices.

Security

• Only this computer. The server accepts only requests addressed to 127.0.0.1:<port> or localhost:<port> and refuses every request from a web browser, so a web page can’t reach it either.
• A token is required and is compared so that nothing can be guessed from the response.
• An allow-list of actions. Each tool may call only fixed internal functions of the app. Deleting, bulk operations, settings and accounts are not among them.
• Safe defaults. Writes are off. If the stored setting is damaged, the server treats it as off.
• Activity log. In Settings → Agents → Activity log you see every call: time, client, tool and result. It is kept for 30 days (at most 5000 rows). Arguments are stored shortened and without the content of e-mails, notes or search terms.
• Watch out for prompt injection. An agent also reads texts written by others, such as e-mails and notes. They can contain hidden instructions that try to steer the agent. Turn writes on only when you know why you need them, and connect only agents you trust.
• Where data goes. Letos gives data only to the agent on your computer. What the agent does next, for example sending it to its AI provider, is governed by that agent’s terms.

More about data is in Privacy and security.

Recipes: example prompts

Write the way you would to an assistant. Start with prompts that only read.

Reading (Read is enough)

• “What is on my plate this week? Go through tasks and calendar and tell me what is too much.”
• “Which unread mail from the last three days needs an answer from me?”
• “How is my goal ‘Run a half marathon’ going? Am I behind?”
• “Find mail from the accountant with an attachment from September.”

Planning (needs write permission)

• “Make me a plan for next week from my open tasks and my calendar. Show it to me first, create nothing yet.”
• “Break the goal ‘Learn Spanish’ into steps for the next quarter. Show me the list and add the steps after I agree.”
• “Move the tasks I won’t finish today to Thursday.”

Mail

• “Archive the newsletters from this week. Show me the list before you do it.”
• “Write a draft reply to the last message from Jana. Don’t send it.”
• “Snooze this thread until Monday morning.”

Tip: for a series of changes, tell the agent to show a plan first. The skill below makes that the default.

Troubleshooting

Problem	What to do
The agent can’t connect	Letos must be running. Check that Allow agents (MCP) is on and under Status that the server Is running. Restart the client.
401, missing or invalid token	The token is wrong, revoked or has an old value. Click New token and run the setup again.
403 from the server	The request didn’t come from your own computer (a different address or a browser). Use http://127.0.0.1:<port>/mcp.
Port is taken by another app	Under Status choose another port (from 1024 up) and click Change port. Then update the address in the client.
“Write refused”	The agent needs the Write permission and Allow writes must be on. The agent should tell you which one is missing.
429, too many requests	You hit a limit. The answer says in how many seconds to try again. The agent should wait that long. Reads 60 per minute, writes 10 per minute and 200 per day.
No mail tools	You are on the cloud endpoint, which has only tasks, goals and calendar. Mail is available over the local connection.
plan_required	The cloud endpoint needs a Plus plan or higher.
not_available	The cloud endpoint isn’t open to this account yet.
An e-mail didn’t go out	You didn’t choose Send in 120 seconds, or you chose Reject. The agent must not assume it was sent.
The agent says an argument is invalid	The tool has strict parameters. Ask it to check the tool reference below.

Everything an agent did is in Settings → Agents → Activity log.

Tool reference

Each tool works with one item at a time. Parameters of every tool are in the MCP tool reference.

Read

Tool	What it does
tasks_list	List of tasks with filters (status, column, goal, due date), in pages.
tasks_get	Task detail (note cut at 4 KB, attachments as details only).
goals_list	Goals with the active step, number of steps and pace.
goals_get	A goal with its steps.
events_list	Calendar events, range at most 62 days.
mail_threads_list	List of mail threads (inbox, archive, spam, unread, sender).
mail_threads_get	Messages of a thread as plain text (at most 8 KB, never HTML).
search	Full-text search of mail (from:, to:, has:attachment, is:unread, in:archive).

Write (only with Allow writes on)

Tool	What it does
tasks_create	Creates a task.
tasks_update	Edits a task (never deletes). On a goal only the title, note and date can change.
tasks_complete	Finishes a task; for a goal step it activates the next one.
goals_add_step	Adds a step to a goal.
events_create	Creates an event with no guests and no repeat, so no invitation goes out.
mail_threads_archive	Archives a thread.
mail_threads_snooze	Snoozes a thread.
mail_compose_draft	Saves a plain-text draft (at most 10 recipients).
mail_send_draft	Asks to send a draft. It goes out only after you confirm (see above).

Advanced: agent skill

A skill is a short instruction file that teaches an agent how to use Letos well: check what it is connected to, read in pages, write one item at a time and agree a plan with you first, wait before retrying after a 429, and treat the text of e-mails as data, not as orders.

• Download the folder in Settings → Agents → Download skill, or directly: letos-mcp.zip. It contains SKILL.md and references/MCP-TOOLS.md.
• In Claude Code unzip it into ~/.claude/skills/ (or .claude/skills/ in a project). In other clients that support skills, add the zip or the unpacked folder the way that client describes.
• The skill doesn’t give an agent any extra permissions. Everything above still applies.
• The files are also readable online: SKILL.md, MCP-TOOLS.md.