Connect a client
The Plavn MCP endpoint and ready-made settings for Claude Code, Cursor and Claude Desktop, a local setup for self-hosting, and how to fix connection errors.
You need a personal access token first. Settings → Developer also shows the commands below with your address already filled in and, right after you create a token, with the token filled in too.
The endpoint
Section titled “The endpoint”| URL | https://api.plavn.com/mcp (for a self-hosted Plavn: your backend’s address followed by /mcp) |
| Transport | Streamable HTTP |
| Authentication | Authorization: Bearer plv_your_token |
| Sessions | None. Every request carries its token. |
Claude Code
Section titled “Claude Code”claude mcp add --transport http plavn https://api.plavn.com/mcp \ --header "Authorization: Bearer plv_your_token"Check it with claude mcp list, then ask “What is due today in Plavn?”
Cursor, Claude Desktop and other clients
Section titled “Cursor, Claude Desktop and other clients”Clients that read an mcp.json take the same URL and header:
{ "mcpServers": { "plavn": { "url": "https://api.plavn.com/mcp", "headers": { "Authorization": "Bearer plv_your_token" } } }}Where that file lives, and whether a client expects url or another key for HTTP servers, depends on the client. Look for
“remote MCP server” or “streamable HTTP” in its settings.
Run it locally (self-hosted only)
Section titled “Run it locally (self-hosted only)”If you run the Plavn backend yourself, an assistant on the same machine can talk to it directly over standard input and output, with no web request:
PLAVN_TOKEN=plv_your_token bun run mcpRun it from the backend folder. It uses the backend’s database as the user the token belongs to, so it needs the backend’s environment. The tools are the same. Most people should use the remote endpoint instead.
Limits
Section titled “Limits”Requests to the endpoint are limited to 120 a minute, counted per network address. An assistant that makes many calls in a row (for example reading dozens of threads) can reach it; it recovers after a minute.
If it does not work
Section titled “If it does not work”| You see | What to do |
|---|---|
| 401, “Use a Plavn personal access token: Authorization: Bearer plv_…” | The token is missing, mistyped, revoked, or not a Plavn token (they start with plv_). Copy it again or create a new one. |
| 429 (too many requests) | Wait a minute and ask for less in one go. |
No write tools (create_task, complete_task, prepare_reply) in the list |
The token is Read only. Create a Read and write token. |
| The client cannot connect at all | Check the URL ends in /mcp and that the client supports remote (HTTP) MCP servers. |
| A tool says “No email with that id” or “No task with that id” | The id is not one of yours, or the item was deleted. Ids come from the other tools’ results. |