Connect your agent

MCP is the connection your agent uses to call Semwright. You need an agent that supports a local MCP server over stdio.

If you have not installed Semwright yet, follow Install and connect your agent. That guide takes you through installation, starting Semwright and a first read-only request.

Use your generated connection settings

semwright setup creates mcp-client.json and prints its location. It contains the exact command path for your installation, so you do not have to work it out yourself.

If your agent has an Add MCP server screen, choose a local / stdio connection, name it semwright and paste the file’s command value into its command field. Leave arguments empty.

If your agent accepts JSON configuration, merge the semwright entry into its existing mcpServers section. The generated settings have this shape:

{
  "mcpServers": {
    "semwright": {
      "command": "<the installed path from your mcp-client.json>"
    }
  }
}

Use the actual path from your file. Keep your other servers and follow your agent’s instructions for where to save its settings.

Codex CLI

If you already have Codex CLI installed, use the command for your system below. These paths match the default installation from this website.

Linux

codex mcp add semwright -- "$HOME/.local/share/semwright/bin/semwright-mcp"

macOS

codex mcp add semwright -- "$HOME/Library/Application Support/Semwright/bin/semwright-mcp"

Windows

codex mcp add semwright -- "$env:LOCALAPPDATA\Semwright\bin\semwright-mcp.exe"

This adds Semwright to your Codex settings. Run codex mcp list to check the entry, then start a new Codex session. If Semwright already has an entry, inspect its settings before replacing it. For a custom install location, use the path in your generated file instead.

In the Codex desktop app, use Settings → MCP servers → Add server. In the IDE extension, use the gear menu’s MCP servers screen. Save the local / stdio entry and restart. These steps follow OpenAI’s MCP instructions.

Start Semwright and reconnect

Run the Broker command printed by setup and leave that terminal open. The agent connection needs this local process to be running under the same user account.

Restart or reconnect your agent to load the new tools, then ask:

Use Semwright to list the capabilities available in this session. Do not modify any files or applications.

If the agent cannot connect, check that the Semwright terminal is still running and that your settings use the generated command path. The Doctor command printed by setup reports connection problems. See troubleshooting for further help.

Choose an application next

A working agent connection does not automatically enable every application. Choose an integration to see its requirements and supported operations. Semwright starts with read-only permissions; use the permissions guide when you are ready to allow changes.

How the connection works

The MCP frontend uses the official Rust MCP SDK and stdio. It delegates requests to the same local broker used by the CLI and inspector. It does not start the broker or grant permissions.

The frontend exposes discovery and execution tools. The agent can search for a capability, inspect its inputs and request an operation. The broker checks permissions before execution.

Session tickets remain sensitive. Keep tickets, private socket material and browser debug endpoints out of shared prompts. Remote hosting, automatic task persistence and operating-system approvals are separate from this connection.

Source: MCP guide and generated configuration, source references checked 7 October 2026.