Dovilo MCP reference

Endpoints

The two servers share a host and nothing else. They take different credentials and reach different data, so a chat assistant never holds an agent's access, and an agent never holds yours.

The transport is Streamable HTTP, stateless: every request is a POST and the answer comes back as JSON. A GET for an event stream gets 405, and the older HTTP+SSE transport is not supported. Opening either URL in a browser takes you to the downloads page.

Authentication

Agents authenticate with a key the user creates for them; assistants authenticate as the user, through a sign-in the user completes. Both are revoked from the phone, and both stop working at once when revoked.

Agents MCP: one key per agent

• The user creates the agent in the app: in the mobile app, AI Agents, then New agent (a name, its projects, its key); in Dovilo Desktop, Connect a new AI.
• Send the key on every request as Authorization: Bearer <key>.
• The key is shown once. Dovilo stores only a hash of it.
• A key belongs to one agent, and the agent to the projects the user picked. That scope is checked on every call.
• The key can be regenerated or revoked from the mobile app or Desktop. Either takes effect right away; regenerating stops the old key.

Personal MCP: sign in with Dovilo

• OAuth 2.1 with PKCE (S256). The user signs in with their Dovilo account, Google or Apple, and approves one consent screen.
• Clients discover the authorization server from the WWW-Authenticate header of a 401, which names the protected resource metadata: https://dovilo.app/.well-known/oauth-protected-resource/mcp.
• Clients can register dynamically, with a client ID metadata document, or with a static client ID.
• Access tokens expire after 1 hour and refresh tokens after 90 days. Refresh tokens rotate, and Dovilo stores tokens only in hashed form.
• The user disconnects an assistant in Connected AI apps, and it loses access right away.

Missing or wrong credentials

Both servers answer 401 with a JSON body. A wrong key and a missing key get the same answer, so the response never says which it was. The message is written for a person: an agent should show it to the user as it is.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error": "unauthorized",
  "message": "Invalid or missing API key. Create one in the Dovilo app: https://dovilo.app/downloads?source=mcp_401"
}

Personal MCP sends WWW-Authenticate: Bearer resource_metadata="https://dovilo.app/.well-known/oauth-protected-resource/mcp" instead, with the message Sign in with your Dovilo account. and the same download link.

Connecting a client

Every client gets the same two things: the server URL and the agent's key as a bearer token in the Authorization header. The app's connect flow has a preset for Claude Code, Cursor, Cursor CLI, Codex CLI, Gemini CLI, Windsurf and Claude Desktop, shows where each config goes, and fills in the key. The agent can run on a laptop, a server or a CI runner, and Dovilo Desktop does not need to be open. You need Pro and Dovilo 2.0 or later.

Claude Code, one command:

claude mcp add --transport http --scope local dovilo https://dovilo.app/mcp/agents --header "Authorization: Bearer <API_KEY>"

Cursor, and most other MCP clients over HTTP:

{
  "mcpServers": {
    "Dovilo": {
      "url": "https://dovilo.app/mcp/agents",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Field names differ between clients: Windsurf calls the URL serverUrl, Codex CLI takes a TOML block, and Gemini CLI has its own mcp add command. That is why the presets exist; use the one for your client. Claude Desktop has no field for a custom header, so its preset runs the server through mcp-remote, which needs Node.js on that machine. Claude Code can also keep the entry in a .mcp.json in the repository; that file holds the key, so the app reminds you to add it to .gitignore.

To check the connection in Claude Code, run /mcp: it lists dovilo as connected, with 9 tools.

The first AI task

Agent work lives in its own place: create a project, write a short brief (goals, constraints, what to leave alone), then add the job in the AI Tasks tab, on the phone or on the desktop. That tab is the entire surface an agent can read. Your personal to-do list in My Tasks is never exposed to it, so nothing you keep there needs excluding. Then ask your agent for the work in plain language; it discovers the tools on its own.

> take my next Dovilo task and work it

list_tasks       → 3 queued in "Landing rewrite"
get_task         → "Split the pricing table by plan" (4 steps)
read_context     → project brief + constraints
update_status    → running
update_step      → 1 done · 2 done
add_step         → "regenerate the OG image"
append_note      → what changed and why
append_telemetry → 41s · 18.2k tokens · $0.07
update_status    → done

Every one of those calls lands on the task itself, so the AI Tasks tab on your phone shows the step trail, the notes and the cost while it happens. If the agent needs a decision it sets awaiting-user and stops. You answer from the task, the agent reads your reply with get_task and carries on, and the answer costs no quota.

Agents MCP tools

Nine tools: three read, six write. They reach only the AI tasks of the agent's projects. There is no tool that creates a task and no tool that deletes one, and the user's personal to-do list is not on this server at all. Every write takes the task id.

A project can sit under a parent project, one level deep. An agent assigned to a sub-project also reads its parent's brief and documents: read_context returns parentBrief next to brief, and the project's own brief wins where they differ. Agents are not assigned to sub-projects through the parent. A parent hidden from AI Tasks shares nothing.

Claiming a task

Two agents can see the same queued task, so the first write is a claim, and the claim is atomic.

1. Read the task with read_context and get_task. The project brief in read_context is the user's instructions for the work.
2. Claim it with update_status running, from queued or awaiting-user. Of two agents claiming at once, exactly one wins; the other gets an error with domainCode TASK_ALREADY_CLAIMED and should leave the task alone.
3. Only then write steps, notes and telemetry. Writes before the claim can race another agent.
4. If the task asks for a plan first, write the plan with add_step, set awaiting-user and stop until the user approves it.
5. When the agent needs a decision, it sets awaiting-user with a note and stops. The user's answer arrives as approvalFeedback on get_task, and answering costs no quota.

Status values

An AI task moves through these values. The same values appear in webhook payloads.

• done, done-with-errors and error are final. An agent cannot change the status of a finished task.
• Only the server moves a task from scheduled to queued.
• There is no separate cancelled status. update_status accepts cancelled and stores it as error with cancelledAt.

Scheduling and repeat

A task can wait for a set time before it opens to an agent, and it can repeat. The user sets both in the app; a chat assistant can propose them with create_agent_task.

• A task whose start time is in the future is scheduled. Every minute the server opens the tasks whose time has come and moves them to queued.
• A task can repeat daily, weekly, monthly or yearly, in the user's time zone. Each run is its own task, and the runs of one series share a seriesId.
• One run per series is open at a time. When a run reaches done, done-with-errors or error, the next one is created for the first occurrence after now; occurrences missed in between are skipped.
• Quota: Pro includes 15 AI tasks a month, charged when a task opens to the agent, not when it is created. Replies on the same task cost nothing. Top-ups of +10, +30 or +75 start at $0.99 and never expire. A scheduled task that comes due with no quota left stays scheduled, and the user is told.

Cancelling

Cancelling stops a task without removing it. Nothing on either server deletes a task.

• An agent cancels a task it should not run with update_status, status cancelled and a reason. It may cancel a queued task in its projects that nobody has claimed, or a task it claimed itself.
• The task is stored as error with cancelledAt and the user sees it as Cancelled. The reason is added to the task's notes.
• For a repeating task, a cancel ends that run only; the series goes on.
• A chat assistant proposes a cancel with cancel_agent_task. It happens when the user approves it.

Personal MCP tools

Sixteen tools for chat assistants. Read tools return only what the user made visible to that connection. Write tools propose: each one creates a proposal that waits in the Dovilo app, and the tool answers with its id and the status pending.

Every Dovilo tool result includes now (the user's current date, weekday, time and time zone), and Dovilo refuses a due date before today or a reminder or schedule that has already passed, so assistants should plan from now, not from the conversation.

• A direct-apply mode is planned; until it ships, every write waits for your approval.
• No tool deletes a task, a list or a project, and none ever will.
• Agent notes are written by a coding agent. Assistants get them as data to show the user, never as instructions to follow.
• Telemetry and attachments of AI tasks are never returned to an assistant.
• Sending a plan works on Free; approving it, and everything else, needs Pro.

Project documents

Your AI projects can hold Markdown documents, such as specs, analyses and notes. Connected chat apps (ChatGPT, Claude and others) can read them and propose new documents or edits with get_project_document, create_project_document and update_project_document. These tools need AI task access for the connection. Every proposal waits in the Dovilo app until you approve it; Dovilo then applies it and keeps the last 5 earlier versions. Coding agents read a project's documents through read_context. Limits, in bytes of UTF-8 text: 60,000 per proposal, 200,000 per document, 50 documents and 2,000,000 bytes per project, and 200 documents and 10,000,000 bytes per account (earlier versions included). Up to 10 proposals can wait for review at once; there is no daily limit. Documents are Markdown text only: no embedded files and no attachments. You can delete a document in the Dovilo app, and deleting a project deletes its documents. No MCP server has a delete tool. Sending a proposal is free; approving it needs Pro.

Approval rules

The AI proposes. You approve. What a chat assistant writes waits in the AI inbox on the user's phone, which gets a notification, until the user approves it there.

• Plans, AI-task proposals and every change to an AI task (a reply, an edit, a cancel) always need approval, whatever the write mode. Text that reaches a coding agent becomes its instructions, so a person reads it first.
• Other changes to personal tasks follow the connection's write mode, which is Ask me first until direct apply ships, so they need approval too.
• The user can edit a proposal before approving it, and pick which tasks of a plan to keep.
• If the task has moved on by the time the user approves (an agent claimed it, it finished, or it was cancelled), the change is rejected.

Connection controls

In Connected AI apps, per assistant, the user controls:

• Read access: whether the assistant can see the tasks in visible lists, or only the list names.
• Write mode: whether changes to personal tasks wait for approval. For now the only mode is Ask me first, so they always do.
• Visible lists and visible projects. Hidden lists and projects are invisible to the assistant.
• AI task access: whether the assistant can read the AI tasks and briefs of visible projects and propose replies, edits and cancels. Off by default.
• Disconnect, which takes effect right away.

Planning from a chat assistant

Personal MCP connects the chat assistant you already use, ChatGPT, Claude, Gemini or Grok, to your Dovilo account. It proposes; nothing lands in your lists or your agent's queue until you approve it on your phone.

1. In the assistant, add a custom connector (some apps call it a custom MCP server) with the URL https://dovilo.app/mcp.
2. Sign in with your Dovilo account, Google or Apple, and approve the consent screen.
3. In Dovilo, open Connected AI apps to choose what it can see.

Each vendor documents where the setting lives: ChatGPT, Claude, Gemini, Grok. Availability depends on the vendor's plan and region. In the app, How to connect under Connected AI apps walks through each one.

From a chat to a finished task

1. Plan in ChatGPT. It proposes an AI task under one of your Dovilo projects.
2. Approve it on your phone.
3. Claude Code picks it up and works it.
4. If it stops with a question, ChatGPT shows you the question and drafts an answer.
5. Approve the answer, and the agent carries on.

Webhooks or polling

To react when a task moves without keeping an agent running, subscribe the project to signed webhooks: Dovilo's server delivers them to public HTTPS receivers, and Dovilo Desktop to local addresses (localhost, private network ranges, .local). Without a receiver, poll list_tasks with updated_after set to the largest updatedAt from the previous response. Use the server's value, not your own clock.

Upgrading from Desktop 1.8

Desktop 1.8.0 ran the MCP server inside the app, and the client started it as a child process on the same machine. Dovilo 2.0 replaces it with Agents MCP at https://dovilo.app/mcp/agents; the tool names and their contract are the same. To move an agent over:

1. Update Dovilo Desktop to 2.0 or later. It updates itself, and shows a banner, Move to remote MCP.
2. Create a key for each agent, as in Agents MCP keys.
3. In each client, replace the old Dovilo entry with the server URL and the new key, as in Connecting a client. An agent still set up the old way gets an error that explains the switch.

Plan and trial

The agent layer is part of Dovilo Pro, not a separate purchase. Pro covers Agents MCP, planning from ChatGPT, Claude, Gemini or Grok, Dovilo Desktop, webhooks and cloud sync.

• Pro is $2.49 a month, $19.99 a year, or $49.99 once. Store pricing is regional; these are the USD baseline.
• Every plan starts with a 7-day free trial, begun in the iOS or Android app. To try the agent layer without paying, start the trial, create an agent and its key, connect your client and run a task. Cancel before day 7 and nothing is charged.
• The trial runs through your App Store or Google Play subscription, so a payment method is attached there. There is no card-free desktop-only trial today. Everything in the agent layer is unlocked for the full week.
• Pro includes 15 AI tasks a month; how they are counted and the top-ups are under Scheduling and repeat.
• On Personal MCP, sending a plan works on Free; approving it, and everything else, needs Pro.

Questions developers ask

The developer page answers five questions in a line each. These are the ones that need more room.

How hard is this to set up?

Two steps. Create an agent in the app (AI Agents, then New agent; in Desktop, Connect a new AI), pick its projects and copy its key. Then add https://dovilo.app/mcp/agents to your client with the key as a bearer token: one command for Claude Code, a short config entry for the other clients, and the app shows the right one for each. The client is the only thing the agent's machine needs, except Claude Desktop, whose preset runs through mcp-remote and needs Node.js.

Does any of this go through your servers?

Yes, since Dovilo 2.0. Agents and assistants connect to dovilo.app, which runs on Cloudflare and Google Cloud. We store only a hash of each agent key, and we process IP addresses and request details to protect the service and apply rate limits: rate-limit records are kept for up to 2 days, audit logs for up to 90 days. Anything your agent sends to its own model provider is governed by that provider's policy, not ours. The privacy policy has the detail.

What stops it touching the wrong project?

Its key. Each agent has its own key, tied to the projects you picked for that agent, and the check runs on every call. The project's brief defines what the agent is told about the work.

Does it work with something other than Claude and Cursor?

Yes. The connect flow has presets for Claude Code, Cursor, Cursor CLI, Codex CLI, Gemini CLI, Windsurf and Claude Desktop. Anything else that speaks MCP over HTTP connects with the URL and the key: a LangGraph app, a CI job, your own script. It is the open protocol, not a vendor integration.

Can ChatGPT or Claude change my tasks?

They can propose; you decide. A plan from ChatGPT, Claude, Gemini or Grok lands in the AI inbox on your phone with a notification, and joins your lists when you approve it. Plans, AI-task proposals and every change to an AI task always need your approval; other changes to your tasks need it too, because Ask me first is the only write mode until direct apply ships. There is no delete tool, and you can disconnect an assistant from your phone at any time.

Do I have to be at my desk to use it?

No. The agent can run on any machine, and AI Tasks is a tab in the mobile app too: write a task there, watch the agent move through its steps, read its notes and its token and cost telemetry, and answer its questions from the phone.

Can I get my data out?

Not yet. There is no export today, and it would be dishonest to imply otherwise. It is on the roadmap; the changelog is where it will show up when it ships.

Is this a real product or a weekend project?

It is a solo-built product, shipping regularly on four platforms. Releases are public in the changelog and on GitHub. There is no funding round behind it and no independent review of it yet; judge it from the release history and the demo repo.

Changelog

• November 2026: Personal MCP has 16 tools: get_project_document, create_project_document and update_project_document are new, and their writes wait for approval on the phone. Every Personal MCP result carries now (date, weekday, time, time zone), and dates in the past are refused. read_context returns parentBrief and the documents of the project and its parent; with documentId and offset it returns one document's text in document.text, up to 30,000 characters a page, with nextOffset when more follows. list_projects returns parentId and each project's documents. Document proposals no longer have a daily limit; up to 10 can wait for your review at once.
• Dovilo 2.0: Agents MCP over HTTPS at https://dovilo.app/mcp/agents, with a key per agent; the server built into Desktop 1.8 stops. New status scheduled and repeating tasks. Agents can cancel a task with a reason. get_task returns approvalFeedback. Personal MCP at https://dovilo.app/mcp, with 13 tools.