让 Claude Code、Codex 直接排查你的服务器：用 MCP 把 SSH 主机接给 AI 编程工具Let Claude Code and Codex Troubleshoot Your Servers: Connecting SSH Hosts to AI Coding Tools over MCP

Claude Code just finished changing an endpoint and, while it was at it, wrote the deploy script too. But the thing actually runs on a server: the logs are there, the process is there, and so is the 502. All it can do is ask “could you paste me the nginx error log?” — so you open a terminal, ssh in, tail, copy, paste it back. Fine once. After an evening of debugging, it is not fine.

Two old answers, neither quite right

One: give it your SSH key. claude-code and codex can both run shell commands, so hand them a key that logs into the server and they will ssh by themselves. The catch is that from then on they can do anything to that server — one misread rm -rf, one helpful systemctl restart, and nothing stands in the way. The key, jump-host config and ports also have to sit somewhere the tool can read.

Two: you become the courier. Safe, but debugging is a back-and-forth: look at logs → look at processes → look at disk → look at logs again. Every step waits for you to run it and paste it back, so the AI is throttled to your copy-paste speed.

What is missing is a layer in between: let the AI go and look for itself, but look only, never touch, and without ever holding credentials. That is exactly the shape MCP is good at.

MCP in three sentences

MCP (Model Context Protocol) is an open protocol that defines how AI applications discover and call externally provided “tools”. An MCP server declares “here are my tools and the arguments each takes”; an AI client (claude-code, codex, Claude Desktop, Cursor…) connects and calls them as needed, and the results flow back into the model's context.

The key point is that the server defines the tools: it decides what is exposed, what is not, and how every call is validated. The model can only order off that menu.

In other words, if the MCP server makes the menu read-only, the AI cannot change anything even if it wants to — no prompt begging it to “be careful” required.

Shellby's approach: credentials stay in, read-only goes out

Shellby is an SSH client for Mac, iPhone and iPad; your hosts, keys and jump hosts are already configured in it. From 2.0.0 the Mac build can run as an MCP server and expose those hosts to the AI coding tools on your desktop. A few hard boundaries are built in:

• The agent sees host names only. Tool arguments say which host; passwords, private keys and passphrases never appear in protocol messages. Shellby opens the connection with the credentials it holds.
• Read-only. Four tools today: list hosts, run read-only commands, read remote files, fetch metrics. Anything that changes system state is recognised by a local classifier and refused, with the reason sent back to the agent.
• Local only, while running only. The server listens on 127.0.0.1 and checks a token on every request; the token lives in the system Keychain. When Shellby quits the server stops — no background daemon.
• Traceable. Every call is one line in an audit log: who, when, which host, what command.

Setup: three steps, five minutes

1. Enable the server. Shellby ▸ Settings ▸ External Agents, flip the switch. The status becomes “Running · port xxxxx” — the port is chosen once and then kept, so you will not have to touch the client config again.
2. Copy the connection command. The same page shows complete commands for claude-code and codex; hit Copy.
3. Run it in a terminal. Done.

The two clients authenticate differently, so the commands look like this (use the port and token from your own Settings page):

# claude-code
claude mcp add shellby --transport http http://127.0.0.1:52731/mcp \
  --header "Authorization: Bearer <your token>"

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

For codex, the export line has to go into ~/.zshrc to persist — which puts the token in a plaintext file. That is how codex works; accept it, or export only when you need it.

Afterwards, run claude mcp list (or codex mcp list) and confirm shellby is listed and healthy.

In practice: chasing a 502

From here it is a normal conversation. Say you tell claude-code:

It will go roughly like this (each step is one MCP tool call, and each shows up in Shellby's audit log):

1. list_hosts — gets prod-web-01's identifier and notices its tags are app nginx.
2. run_command: tail -n 50 /var/log/nginx/error.log — finds a run of upstream prematurely closed connection while reading response header from upstream … 127.0.0.1:3000.
3. get_metrics — load 3.9, memory at 91%, top CPU consumer is node.
4. read_file: /etc/nginx/conf.d/app.conf — confirms the upstream really points at port 3000 and the timeouts are defaults.

Then the verdict: the Node process is pegging the CPU, responses exceed nginx's upstream timeout, hence 502. At this point it may be tempted to “just” systemctl restart app — Shellby refuses that and tells it that commands which change system state are not allowed right now. It writes the recommendation down for you, and you decide whether to run it yourself in Shellby.

You never opened a terminal, and you never handed over a credential.

Details you only notice once you use it

Why does it sometimes get refused “unfairly”?

The classifier judges the whole line. cat a.log && systemctl status b is read-only, but grep x a.log > /tmp/out writes a file through redirection and is refused. The tool description Shellby gives the model already says “single, independently reviewable commands; don't chain unrelated steps with &&; don't rewrite a refused command to sneak past” — in practice the model rarely trips over this.

What if the output is huge?

A single call returns at most 64 KB; beyond that it is truncated and the model is told truncated: true, so it narrows the query itself (grep, tail). That is how big logs should be read anyway — not by cat-ing the whole thing into context.

Does it reuse my open sessions?

Yes, and preferentially. A machine you are connected to in Shellby answers the agent almost instantly; only otherwise is a new connection opened. Jump hosts and Mosh-compatible transport follow the host config, so the agent never needs to know about them.

What if the token leaks?

“Reset access token” on the Settings page — the old token dies immediately; re-add with the new command and you are done.

What it does not do

• No writes. Restarting services, editing config and writing files are not exposed. Mutating commands behind an approval card are planned, but only after the read-only version has proven itself.
• Not on iPhone / iPad. The consumers are desktop coding tools, and iOS background limits would suspend a local service at any moment.
• No background daemon. Keep Shellby open while you use it; that is a deliberate choice.
• No “raw ssh” tool that bypasses the classifier. Not even “for debugging” — if it existed, the agent would always prefer it and every guardrail would be decoration.

In short

Connecting an AI coding tool to your servers comes down to one question: how much power are you willing to hand to an automation that will sometimes be wrong? MCP lets that power be defined precisely, and Shellby defines it as “read-only, never sees credentials, always leaves a trace”. That already covers troubleshooting, reading logs and checking status — most of the everyday work — with almost no attack surface. The small remainder that needs hands on the keyboard stays yours.

Full parameters and limits are in the External Agents · MCP documentation.