Skip to content

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.

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.
Terminal window
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?”

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.

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:

Terminal window
PLAVN_TOKEN=plv_your_token bun run mcp

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

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.

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.

Tools reference.