Tools and action providers

Everything DeskMate’s character can do is an action, supplied by an action provider. The deliberation loop sees one flat list of tools; where each came from doesn’t matter to it.

A game connected through a Neuro SDK–compatible endpoint is planned as a fourth provider (ADR-0003); it isn’t implemented yet, so there is no guide for it.

Adding an MCP serverCopy Anchor Link

DeskMate is an MCP client. It supports:

• stdio servers — a command that DeskMate launches and talks to over stdin/stdout;
• Streamable HTTP servers — a URL, with authentication only as header values you type in. There is no OAuth flow.

It doesn’t support the legacy SSE transport, nor the optional MCP features elicitation and sampling; a call that needs user input fails and the reason goes back to the task.

In Tools, paste the same mcpServers JSON that servers document for Claude Desktop. Either the whole file or just the object inside mcpServers works:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    },
    "docs": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer …" }
    }
  }
}

• A name is 1–40 characters of letters, digits, _, . and -.
• type may be omitted: an entry with command is stdio, one with url is HTTP.
• DeskMate connects once before saving; if that fails, nothing is saved and you see why.
• env and headers values are stored with your API keys and never sent back to the console.
• Apps launched from Finder don’t get your shell’s PATH, so DeskMate reads it once from your login shell before starting a stdio server.
• Adding a server is granting it access. Each server has an on/off switch, and tool lists follow the server’s listChanged notifications.

The model sees each tool as <server>__<tool>, cut to 64 characters, with characters outside a-z A-Z 0-9 _ - replaced by _.

SchemasCopy Anchor Link

Tool input schemas are lowered to a common JSON Schema subset when registered. A tool whose schema can’t be lowered isn’t shown to the model.

What counts as riskyCopy Anchor Link

A call is risky if any of these holds:

1. The provider says so. For MCP tools, that means the tool declared neither readOnlyHint: true nor destructiveHint: false in its annotations. A tool with no annotations is risky.
2. You marked it risky.
3. For the computer provider only: a semantic rule on the control about to be pressed, such as a button named Send, Delete, Buy, Submit or Pay (English or Chinese), pressing Return, or replacing text that is already there. MCP tools don’t get this rule — too many false positives from search terms.

Your overrides win: in Tools you can set any tool to ask, don’t ask, or off, and set a whole server to trusted. After adding a server, DeskMate immediately lists which of its tools count as risky so you can adjust them on the spot.

Confirmation requestsCopy Anchor Link

A risky call makes a confirmation request: a card by the character with the task, the server and tool, the reason, and the arguments, with Decline and Approve. The same requests are listed in the console’s Tasks page.

• Approve works by click only. Not by voice, so an echo or a bystander can’t approve anything.
• There’s no timeout. Cancelling the task withdraws the request.
• While a task waits for approval, tasks behind it wait too.
• If the character window is hidden, a new request shows it (without taking focus).

Leak protectionCopy Anchor Link

Read-only isn’t the same as safe: a web page could talk the model into reading a local file and then sending it out through a “read-only” tool that reaches the internet. So, per task:

• once a task has used a tool that does not touch the outside world (openWorldHint: false, e.g. reading a local file), or has read an app’s window,
• every later call to a tool that may reach outside (openWorldHint not false) needs confirmation, and the request says why.

For computer, the unit is a place: an app, or each website inside a browser. Reading in one place and then typing in another needs confirmation; reading and typing in the same place doesn’t. This rule beats a server’s “trusted” setting and per-tool overrides.

What the character may start by itselfCopy Anchor Link

Who started the task decides the rules (ADR-0006):

The reason for “never asks”: the character speaks up because of what’s on your screen, and a web page can try to steer it. If those tasks could raise approval cards, outside content could manufacture a stream of them — and a stream of cards trains people to click without reading.

Other limits: one task runs at a time with up to 3 waiting; a task is capped at 40 tool steps and 10 minutes of working time (waiting for approval doesn’t count); each tool result is cut to 8,000 characters before the model reads it; a self-started task is at least 30 minutes after the last one. ⌃⌥⌘Esc is the emergency stop: it cancels tasks and stops speech.

Authorizing apps for computerCopy Anchor Link

computer authorizes per app, at three levels: read only, operate, and trusted (button names and Return no longer ask). The first time a task touches an app, a card asks; approving puts the app at operate. You can change or revoke it in Tools. DeskMate itself, System Settings, terminals, Script Editor, Keychain Access and password managers can never be authorized.