mcpTools

Adds tools to the MCP server that agents can call, with params and an output shape.

Details #

Switchboard runs an MCP server so agents such as Claude can use it. An mcpTools entry adds one more tool to that server, backed by your extension's code. Use it to let an agent read from or act on something your extension knows about.

Declare it in switchboard.json under adds.mcpTools. Every entry has an id (lowercase, digits and . _ -, up to 64 characters, starting with a letter), a title (1 to 80 characters) and an optional description. Ids must be unique within the list.

{
  "adds": {
    "mcpTools": [
      { "id": "open-ticket", "title": "Open a ticket", "params": { "type": "object", "properties": { "key": { "type": "string" } }, "required": ["key"] } }
    ]
  }
}

Gotchas #

A tool that is not turned on is refused for agents (HTTP 403) even though the extension is installed.
Agent calls are traced like a macro run and rate limited.
A call that takes more than 30 seconds without answering fails.
Only set readOnly: true when it is true. It lets an agent call the tool without asking.
The manifest checks the entry's shape; the handler does the work. Without a matching handler the extension doesn't load.
Unknown keys in an entry are refused.

The sample below can be downloaded from the Full example section and edited into your own.

Where it shows up #

Settings > Agents & MCP has a section, "Extension tools agents may use", and the extension's page in the Extensions window lists the same tools. Each has a switch. Agents see nothing until you turn a tool on. Turning it on is remembered per tool as <extension id>/<tool id>.

Agents see each tool under a name made from the extension's short name and the tool id, with dashes turned into underscores, for example things_add_todo.

The handler #

The handler gets the arguments the agent chose, shaped by params, and the usual ctx. It returns any JSON value. Throw an Error with a clear message to report a problem; the agent sees it.