outboundctl mcp

outboundctl mcp runs a Model Context Protocol server on standard input and output, so Claude, Cursor, Codex, Gemini or any MCP client can ask about this Mac’s network. It speaks JSON-RPC 2.0, one message per line. Reading tools answer at once; the five change tools only file a request that you allow or refuse in Outbound. For the app-side view, see AI apps and MCP and approving AI changes.

Running the server

outboundctl mcp [--read-only] [--toolsets traffic,rules,trackers,review] [--detail domains|hosts] [--ledger <file>]
outboundctl mcp --print-disclosure

Reads until its input ends, then waits for outstanding change requests before exiting. On initialize the server names itself outbound and adopts the client’s name, which is what the approval message in Outbound shows. It implements initialize, ping, tools/list and tools/call, plus the resources and prompts below.

Flag	What it does
--read-only	Offers no tools that change anything
--toolsets	Offers only the listed groups: traffic, rules, trackers, review
--detail domains	The default: results name website domains, not full host names
--detail hosts	Full host names, addresses and local names, only while “Let AI apps see host names” is on in Settings › Intelligence; otherwise it falls back to domains
--print-disclosure	Prints the disclosure policy the server would use, as JSON, and exits without starting the server
--ledger <file>	Records successful tool results for the Assistant’s checks (see below)

An unknown --detail value or toolset name is a usage error (exit 64).

What results show

With the default --detail domains, results show website domains instead of full host names: api.example.com appears as example.com. IP addresses and networks appear as address, local names as local network, and app paths as app names. User names are never included. Rules returned by rules follow the same policy. audit_events follows the organisation’s audit detail setting for remote hosts.

The tools

There are 26 tools in four groups. These read and change nothing:

Tool	Group	What it returns
network_summary	traffic	Totals for a window (connections, blocked, bytes) with the top apps, domains, countries and new apps
top_apps	traffic	The apps that connected most, by data then connections
top_domains	traffic	The website domains reached most, by connections
top_countries	traffic	The countries whose servers were reached most, as ISO codes
blocked	traffic	Blocked connections: totals and the apps and domains blocked most
new_apps	traffic	Apps that connected for the first time in the window, newest first
traffic_over_time	traffic	Connections and bytes in each hour or day
app_activity	traffic	What one app sent: totals, domains, countries and ports
recent_connections	traffic	History rows
alerts_spikes	traffic	Upload spikes detected in the last seven days
audit_events	traffic	Audit lines in a window, from the app’s copy of the sealed log (not the authoritative record)
audit_sinks	traffic	Each configured audit sink’s last delivery, backlog and last error; an unmanaged Mac has none
firewall_status	rules	Whether the filter is configured and on, and the rule count
rules	rules	The firewall rules: action, remote, ports, protocol, program, on or off
explain_connection	rules	Why the saved rules decide a connection
change_status	rules	The decision on a change request; it cannot approve one
tracking_report	trackers	Tracker companies and apps
tracker_lookup	trackers	The catalogue label for a host, or null
app_optouts	trackers	Switches a company already offers for an app
likely_telemetry	trackers	Unverified local suggestions; they never become blocks from this tool
review_queue	review	Connections waiting for a decision; you decide them in the Outbound app

These ask you to make a change:

Tool	Group	What it asks for
add_rule	rules	Add a rule
remove_rule	rules	Delete one of your rules
set_rule_enabled	rules	Turn one of your rules on or off
activate_profile	rules	Switch the active profile; none turns every profile off
block_trackers	trackers	Block known trackers for one app, listing endpoints that may affect the app separately

The analytics tools take a window (hour, day, week, month, year, default day). Ranking tools, blocked and new_apps also take a limit (1 to 20, default 10). network_summary has no limit parameter and uses up to 8 rows per ranking and 5 new apps. rules takes a limit up to 200 and defaults to 50.

Resources and prompts

The server also lists read-only resources: outbound://status, outbound://rules, outbound://catalogue/info, outbound://review, outbound://connections/live (at most one update every five seconds) and outbound://notices, plus templates for one rule, one app’s activity, one tracker company and one change request.

Its prompts are why_blocked, what_did_app_send, tracker_cleanup and weekly_review. tracker_cleanup prefers the company’s own opt-out switch, then a dry-run block that you approve.

Changes need your approval

The five change tools never change anything by themselves. The request is written beside the rule store, the background agent shows it to you in Outbound with the AI app’s name and the reason the model gave, and the change is made only if you allow it. An allow that would loosen protection still asks for the usual approval. So the tools take a reason, and the server’s instructions tell the model to explain why.

Three change requests per server process can wait for you at once; a fourth is refused with a message telling the model to ask again later. A request nobody answers within 3 minutes fails with Nobody answered in Outbound in time, so nothing changed. Make sure Outbound is running, then ask again.

add_rule takes action (allow or deny), remote, optional ports (default any) and proto (default any), and can name the program with either signing_id and team_id (the team is optional only for Apple’s own com.apple. identifiers) or path. The spec is validated before the request is filed, so an invalid rule is rejected at once. An approved add returns approved with the new rule_id.

The ledger

outboundctl mcp --ledger <file>

This form is how Outbound’s own Assistant runs the server. Successful tool results are appended as JSON, one result per line (an object or array), and the Assistant checks each number in the agent’s answer against that record rather than against what the agent says it saw. The file is appended to, never replaced; a symlink is refused; a new file is created readable only by you; and it stops growing at 4 MB.

Installing into an MCP client

outboundctl mcp install --client claude-code|claude-desktop|cursor|codex|gemini|vscode [--dry-run] [--read-only] [--toolsets <names>] [--detail domains|hosts]

Adds Outbound to that client’s own configuration file, merging with what is already there rather than replacing it:

Client	File
claude-code	~/.claude.json
claude-desktop	~/Library/Application Support/Claude/claude_desktop_config.json
cursor	~/.cursor/mcp.json
codex	~/.codex/config.toml
gemini	~/.gemini/settings.json
vscode	~/.copilot/mcp-config.json

The registered server is named outbound and runs the resolved path of the outboundctl you invoked with the mcp argument. Run the bundled copy to register that copy. --dry-run prints the file and the changes it would make without writing anything. For JSON clients, the installer replaces the outbound entry while keeping the other entries. Codex’s TOML file is only ever appended to, and if it already defines an Outbound server for a different copy of the app, the command leaves the file alone and prints the block you would need. For Claude and VS Code, the command reminds you to restart the client to load the server. --read-only, --toolsets and --detail are written into the client’s configuration, so the client launches the server with them.

Omitting app selectors from add_rule requests a rule for every program; empty selectors are rejected. remove_rule takes id and reason; set_rule_enabled takes id, boolean enabled and reason. Take IDs from the rules tool. Settings › Intelligence can turn AI rule changes Off.

The server exits 0 when input and outstanding requests finish. Tool failures are JSON replies with isError: true, not process exits. An unwritable ledger exits 1. Installation succeeds with exit 0, reports invalid client selection with exit 64, and file or merge errors with exit 1. For example, outboundctl mcp install --client cursor --dry-run previews the merged configuration.