Browse the docs

list_macros

Lists the macros you exposed to agents, with their inputs, whether they ask for approval and the tool name each one has.

Details #

Switchboard ships an MCP server, switchboard-mcp, that agents start themselves over stdio. It is a small program inside the app, at Switchboard.app/Contents/Helpers/switchboard-mcp. It talks to the running engine, so Switchboard must be open.

Agents only see what you expose. A macro is visible to an agent only when its agent.exposed setting is on. Macros are never exposed by default. The one exception is a macro an agent created itself: it can lint, dry-run, read the trace of and update its own work.

{ "agent": { "exposed": true, "approve": "always", "destructive": false, "description": "Paste a ticket key as a title" } }

approve is never, phone or always. A macro that is destructive, or whose approve is not never, waits for you before an agent runs it.

Each exposed macro is also its own tool. Next to the seven built-in tools, the server lists one tool per exposed macro. The tool name is the macro name as a snake_case slug (Ask a question becomes ask_a_question). A name that clashes with a built-in gets a macro_ prefix; two identical slugs get _2. The tool's inputs are the macro's inputs, and its description is the macro's description (the line under its name in the editor). Calling it runs the macro, with the same approval and rate limit as run_macro. Exposed macros also appear as resources (switchboard://library/<group>/<macro>.json), and switchboard://traces/recent lists the latest runs.

Every run is tagged. Runs an agent starts are recorded with byAgent set to the client's name (what the client sent in initialize, such as claude-code), so Activity and traces show who ran what.

Rate limit. All agents together may start 60 runs a minute. Past that, a call returns an error telling the agent to wait.

Approvals. When a run needs approval, the server writes a request file in the approvals folder of the support folder and waits. It is answered by approving or denying in Switchboard. If no answer comes in 5 minutes the run does not start. Start the server with --approval-timeout <seconds> to change that.

Adding it to an agent #

For Claude Code:

claude mcp add switchboard -- /Applications/Switchboard.app/Contents/Helpers/switchboard-mcp

For Claude Desktop, add this to ~/Library/Application Support/Claude/claude_desktop_config.json, and for Cursor to ~/.cursor/mcp.json, then restart the app.

{
  "mcpServers": {
    "switchboard": {
      "command": "/Applications/Switchboard.app/Contents/Helpers/switchboard-mcp",
      "args": []
    }
  }
}

If you use a non-default SWITCHBOARD_HOME, add "env": { "SWITCHBOARD_HOME": "/path" } to the entry.

This tool #

Arguments are both optional.

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "list_macros", "arguments": { "group": "Work", "query": "ticket" } } }

The result is a text block holding a JSON array:

[
  {
    "id": "m_4f2a9c",
    "name": "Paste ticket as title",
    "tool": "paste_ticket_as_title",
    "group": "Work",
    "description": "Paste a ticket key as a title",
    "inputs": [{ "name": "key", "type": "string", "required": true, "description": "Ticket key" }],
    "asksApproval": true,
    "destructive": false,
    "timeoutSeconds": 60
  }
]

Gotchas #

  • An empty array means nothing is exposed, not that the Library is empty.

  • If the engine is not running the call returns an error saying Switchboard must be opened.

See also #