Models & MCP

01Choose a connection

Which provider and model combinations are validated for the release is still being confirmed.

02Understand the parts

03Set up an MCP client

Connect a local MCP client to Mecum to observe and operate macOS applications, use Chrome and, if you allow it, read passive interaction events and shared memory. Your client supplies the model; the running Mecum app supplies the tools.

Mecum exposes its bridge over local STDIO, so the client and Mecum run on the same Mac. The helper is included in Mecum.app and needs no separate Node.js or Python installation. There is no public HTTP or SSE endpoint and no hosted OAuth connector. Tool results go to your client and may be sent to its model provider: a local bridge does not mean local model inference.

Prepare Mecum

1. Put Mecum.app in a stable location, such as /Applications, then open it. Keep Mecum running while a client uses its tools.
2. Grant the macOS permissions Mecum requests for the features you use: Accessibility and Screen Recording for desktop control and perception, Input Monitoring for passive watching. Chrome connection authorization is separate.
3. Open MCP → MCP Connections… from Mecum’s menu bar.
4. Name the client, select its capabilities and click Add Client. Create a separate entry for each client you connect.
5. Turn Enabled on and wait for Ready.
6. Expand Client configuration and use Copy Claude Code command, Copy Codex command or Copy JSON. These carry your actual paths and client ID.

The generated configuration is the preferred way to install. The examples on this page are public templates: they are not credentials, and they do not run until you replace the placeholders.

Replace YOUR_USERNAME and CLIENT_UUID with the values copied from Mecum. If Mecum is elsewhere or uses a custom support directory, use the generated paths instead. Do not create a connection file yourself or copy another person’s file.

Use absolute paths in JSON and TOML; do not substitute ~ or $HOME there. Keep the spaces inside each path string: an argument containing a path is one argument. mecum-bridge is the executable; mcp-bridge is its required first argument.

Merge the entry into the client’s existing settings and keep unrelated servers. These machine-specific settings belong in your personal configuration, not in a shared repository.

04Configure your client

Claude Desktop, Cursor, Gemini CLI, Cline and Cascade use an mcpServers object with this command and these arguments. Where each one keeps it is listed below.

{
  "mcpServers": {
    "mecum": {
      "command": "/Applications/Mecum.app/Contents/Helpers/mecum-bridge",
      "args": [
        "mcp-bridge",
        "--connection",
        "/Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json"
      ]
    }
  }
}

No URL, API key, OAuth login or environment variable is needed for this bridge. Mecum creates and rotates the local connection credential; your client’s own model login stays separate.

Claude Code

Prefer Copy Claude Code command in Mecum. The equivalent template:

claude mcp add --scope user --transport stdio mecum -- \
  "/Applications/Mecum.app/Contents/Helpers/mecum-bridge" \
  mcp-bridge --connection \
  "/Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json"

Check the registration with claude mcp get mecum, then start a new Claude Code session and use /mcp to check the live connection. User scope makes the configuration available across your projects. If mecum already exists, inspect and update that entry instead of adding a duplicate. Reference: Claude Code MCP configuration.

Codex CLI and IDE extension

Prefer Copy Codex command in Mecum. The equivalent template:

codex mcp add mecum -- \
  "/Applications/Mecum.app/Contents/Helpers/mecum-bridge" \
  mcp-bridge --connection \
  "/Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json"

Alternatively, add this to ~/.codex/config.toml:

[mcp_servers.mecum]
command = "/Applications/Mecum.app/Contents/Helpers/mecum-bridge"
args = [
  "mcp-bridge",
  "--connection",
  "/Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json"
]

Use codex mcp list to check the registration and /mcp inside Codex to inspect active servers. Restart an existing client session after changing the configuration.

ChatGPT desktop or Codex desktop host

For desktop versions that expose local MCP settings, open Settings → MCP servers → Add server, choose STDIO and enter:

Save and restart the server. Desktop, Codex CLI and IDE configuration is shared for the same Codex host, so avoid duplicate entries. Reference for Codex and this host: OpenAI MCP configuration.

Claude Desktop

Open Settings → Developer → Edit Config and merge the shared JSON template into ~/Library/Application Support/Claude/claude_desktop_config.json. Quit Claude Desktop completely and reopen it. Check Mecum’s connection status in Developer settings and confirm its tools appear in the conversation’s tool controls.

This is the local MCP setup for Claude Desktop. It does not install a hosted connector for claude.ai or establish Cowork compatibility. Reference: MCP local-server setup for Claude Desktop.

Cursor

Merge the shared JSON template into your personal configuration, ~/.cursor/mcp.json. Open Cursor’s MCP settings, enable or reload the server and confirm its tools are available to the agent. A project configuration can override a personal entry with the same name, so inspect it if Cursor uses an unexpected path. Reference: Cursor MCP configuration.

VS Code with GitHub Copilot

Open the Command Palette and run MCP: Open User Configuration. VS Code’s MCP configuration uses servers rather than mcpServers:

{
  "servers": {
    "mecum": {
      "type": "stdio",
      "command": "/Applications/Mecum.app/Contents/Helpers/mecum-bridge",
      "args": [
        "mcp-bridge",
        "--connection",
        "/Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json"
      ]
    }
  }
}

Save, use MCP: List Servers to start or restart Mecum, and select its tools in Copilot’s agent workflow. Keep the server in the local user configuration: a container or remote host cannot use this Mac’s executable and loopback connection. Reference: VS Code MCP configuration.

Gemini CLI

Merge the shared JSON template into ~/.gemini/settings.json, keeping any existing authentication and model settings. Start a new Gemini CLI session and check the server with gemini mcp list. Use /mcp inside Gemini CLI to inspect available servers and tools, and keep the client’s normal tool-approval settings. Reference: Gemini CLI MCP configuration.

Cline

In the extension, open MCP Servers → Configure → Configure MCP Servers and merge this into its settings file:

{
  "mcpServers": {
    "mecum": {
      "command": "/Applications/Mecum.app/Contents/Helpers/mecum-bridge",
      "args": [
        "mcp-bridge",
        "--connection",
        "/Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

For Cline CLI, the configuration file is ~/.cline/mcp.json. Enable or restart the server through Cline’s MCP controls. The empty autoApprove list leaves tool approvals with the client. Reference: Cline MCP documentation.

Windsurf or Cascade

Use Cascade’s MCP controls to Open MCP config file, then merge the shared JSON template under mcpServers. Enable the server and check its tools in Cascade.

Use the file your installed editor opens. The current documentation redirects to Devin Desktop and lists ~/.config/devin/mcp_config.json; older Windsurf installations can use a different location. Reference: Cascade MCP configuration.

Other local MCP clients

A client that can launch a local STDIO server uses the same values:

Transport: stdio
Command:   /Applications/Mecum.app/Contents/Helpers/mecum-bridge
Arguments:
  mcp-bridge
  --connection
  /Users/YOUR_USERNAME/Library/Application Support/Mecum/MCP/CLIENT_UUID.connection.json

If a client requires one array with the whole command, put the executable first, followed by the three arguments. Follow that client’s configuration schema: not every client uses an mcpServers wrapper.

If the interface only accepts a server URL, this local configuration cannot be pasted there. Mecum provides no public HTTP or SSE endpoint and no hosted OAuth connector, so a direct web or cloud connection needs a separate integration: this is not ChatGPT web, claude.ai or cloud-agent support.

05Choose capabilities

Desktop apps and Browser are selected by default when you create a grant; Passive Watcher and shared memory need an explicit selection. Without shared memory, the client has its own Brain and no access to the shared living-memory store. Watcher events are not learned automatically.

The helper forwards requests to the running app. It does not grant macOS permissions or start Mecum. Changing a grant’s capabilities means revoking it and creating a new one.

06Test the MCP connection

Start with this read-only prompt in your configured client, with Desktop apps enabled:

Use Mecum to report permission status, list running applications and list the open windows of one application. Do not open, move, click or change anything.

Confirm that the client actually calls Mecum’s tools and returns their results. A saved configuration alone does not prove a working connection.

For a later operation, name the app, the window and the intended result. For example:

Use Mecum in Pro Tools. In the I/O Setup window, select Output Busses in the All Busses filter. Observe first, verify the resulting value, and stop if the target is ambiguous. Do only this operation.

That application and window must already be available, and the selected Mecum build must permit the operation. Client connectivity does not establish compatibility with every application or macOS build.

Mecum supplies workflow instructions when the MCP session starts. Agents call task_begin with your request before desktop or browser work, then task_end with completed, failed or interrupted. status, apps and windows are available without a task. Calling a task completed does not by itself show that a UI action succeeded, nor qualify it for learning.

07Several clients, stopping access

Each Mecum grant accepts one active connection at a time, including connections opened for tool discovery. Create separate grants for Claude Desktop, Claude Code, Cursor and any other client that runs independently; each gets its own connection-file path.

Shared settings do not remove this limit. For clients that share one configuration, use one frontend at a time unless you arrange separate grants and configurations. A health check can also find a grant already in use.

All clients still share Mecum’s Seat broker, browser profile pool and passive Watcher. Separate grants do not mean simultaneous, unrestricted control of the same app, Chrome profile or Watcher run.

Turn Enabled off to stop access and keep the grant. Revoke removes the saved authorization. Quitting Mecum disconnects clients; after you reopen it, restart or reconnect the client, because the helper does not reconnect or replay requests on its own.

08Troubleshoot an MCP client

Never publish the contents of a *.connection.json file: it holds a local connection credential. Share the templates, never live connection files. Public instructions need no real username, client UUID or token.

09Check a worker connection

1. Provider: the connection light on the provider’s Settings page, or Check All in Connections, says whether the sign-in, key or server answers.
2. Model and Effort: chosen per worker in the conversation composer; a model the provider does not serve fails the turn.
3. Tools: an agent is given Mecum’s tools and nothing else; a model without tool support answers in text only.
4. Desktop: the first tool call that needs the computer asks for a seat; the worker’s row reads Waiting for the computer until it holds one.

A successful text reply verifies the model connection only. It does not verify tool access or a desktop workflow.

10Follow a tool request

Each round observes afresh; a saved observation is never a coordinate for later input.

11Diagnose an interruption

For stopping a worker, see Stop and inspect. For an external client, see Troubleshoot an MCP client.

12Context and credentials

Task instructions, conversation context, window text and recalled app knowledge can be included in a model request. Running the client on your Mac does not keep inference local when it calls a remote provider.

Moving a worker between a local server, a subscription and an API key asks for your consent first, because messages and worker instructions change destination. Web search, on by default for Claude Code and Codex, is a separate switch under Settings → Chat → Web.

Use the authentication mechanism supplied by the app or client. Keep credentials out of task instructions and chat messages. See Permissions & data for local processing and model-request boundaries.