外部 Agent · MCPExternal Agents · MCP

From macOS 2.0.0, Shellby can run as an MCP server that exposes the hosts you have already configured to AI coding tools on your desktop — claude-code, codex, and any other MCP client. They no longer need your passwords, private keys or jump-host setup; they just say “run this on prod-db”. Everything exposed today is read-only.

The problem it solves

AI coding tools write code locally, but deploys and debugging happen on servers. Until now you had two options: hand the tool your SSH key (after which it can do anything to your servers), or open a terminal yourself and ferry output back and forth. Shellby adds a third:

Requirements

• macOS, Shellby 2.0.0 or later. There is no MCP server on iPhone / iPad — the consumers are desktop coding tools, and iOS background limits would suspend a local service at any moment.
• Shellby must be running. The server lives inside the app process and stops when the app quits. There is deliberately no background daemon: a process that can reach all of your servers should not sit unattended in the background.
• An MCP client that speaks Streamable HTTP. Tested with claude-code and codex.

Turn it on and connect

1. Enable the server — Settings ▸ External Agents, switch on “Expose to external agents”. The status changes to “Running · port xxxxx”. The port is picked at random the first time and then kept, so clients are configured once.
2. Copy the connection command — the “Connection commands” block on the same page has a complete command line per client; hit Copy.
3. Run it in your terminal. Then ask claude-code to “check the recent nginx error log on prod-web-01” and it will call Shellby's tools by itself.

The two clients authenticate differently, so the commands differ:

# claude-code: the token can go straight into a header
claude mcp add shellby --transport http http://127.0.0.1:<port>/mcp \
  --header "Authorization: Bearer <token>"

# codex: only accepts an environment variable name, hence two lines
export SHELLBY_MCP_TOKEN=<token>
codex mcp add shellby --url http://127.0.0.1:<port>/mcp \
  --bearer-token-env-var SHELLBY_MCP_TOKEN

What is exposed

The host argument accepts either the name or the id returned by list_hosts. Calls reuse a session you already have open before opening a new connection — so a machine you are connected to in Shellby answers the agent almost instantly.

What gets refused

Anything that would change system state — installing, restarting services, writing files, deleting, redirecting into system paths — is refused, and the reason is returned to the agent. The decision is made by Shellby's local command classifier, the same one the built-in AI Agent uses; how the model describes the command plays no part. Your deny list from the AI settings applies to external agents too; your allow list does not — that is a relaxation you made for the in-app AI, and it is not quietly extended to outside tools.

Rules you will actually run into:

• Chaining unrelated commands with && makes the whole line inherit its most dangerous part, so it may be refused as a whole — the tool description already tells the model to “write commands as single, independently reviewable lines”.
• Wrapping a command in bash -c, piping into a shell, or writing files via redirection are all recognised as non-read-only.
• There is no “raw ssh” tool that bypasses the classifier. Deliberately: if one existed, the agent would always prefer it and every guardrail would be moot.

Security boundary

• Loopback only (127.0.0.1); cross-origin requests from web pages are rejected to defeat DNS rebinding.
• A bearer token is checked on every request. The token lives in the system Keychain, never in a plaintext file; other programs on the same Mac cannot call the service without it.
• Credentials never leave the app. Tool arguments accept host names only; passwords, private keys and passphrases never appear in MCP messages.
• Output is redacted first. Command output and file contents pass through the same local redaction as the AI Agent (following your AI redaction setting) before they are returned — the external agent will forward them to its own model provider.
• The token can be reset at any time — the old one is invalidated immediately, and configured clients must be re-added with the new command.

Audit log

Every call is recorded as one line: time, client, tool, target host, command summary, result (exit code or failure reason). View, copy and clear it under Settings ▸ External Agents. Command output is not recorded — it may contain sensitive data and its size is unbounded. The log stays on this Mac and is not synced.

FAQ

The agent says it cannot connect?

Check that Shellby is running and the switch is on, then compare the port in your connection command with the one shown in Settings (resetting the token keeps the port but changes the token).

Can it restart services or edit config?

Not yet — this release exposes read-only capabilities only. Mutating commands behind an approval card, and file writes with the same diff preview the in-app AI Agent uses, are planned for later releases.

Can several clients connect at once?

Yes; they share the port and token. The “client” column in the audit log tells them apart.

Does it need Pro?

No. The feature spends your own AI quota in claude-code / codex; Shellby only provides the channel.