MCP troubleshooting
Diagnose problems with Subshell MCP integration and communication.
No Subshell tools
Confirm the agent is running inside a Subshell-launched pane. Check MCP configuration, including the one-time setup required by Gemini CLI, Qwen Code, Cline, Open Interpreter, OpenHands, Grok Build, Hermes, and pi. OpenClaw panes carry no Subshell tools by design for now: its MCP registration is Gateway-scoped rather than per-session, so cross-subshell comms are not wired. See OpenClaw.
Run subshell-server status on the server host to see which MCP executable it uses. If you've configured MCP manually, check that the executable exists on the machine where the agent runs.
Missing identity environment
subshell mcp: SUBSHELL_API_KEY is not set and subshell mcp: SUBSHELL_ID is not set mean the process lacks pane identity. Don't invent credentials or reuse another pane's environment.
Codex starts, but Subshell MCP fails
Open /mcp in Codex and inspect the startup error. If it says
SUBSHELL_API_KEY is not set, the MCP process didn't receive the subshell's
credential, even if Codex's shell can access it.
Subshell's Codex harness forwards the required variables automatically on new
launches. For an older or manual registration, check the env_vars setting in
Codex's configuration on the machine where the agent runs:
-
Under the execution account, open
~/.codex/config.toml, or the file under your customCODEX_HOME. See Files and paths. -
Add or update
env_varsin the existing[mcp_servers.subshell]table. Keep its command and arguments. A complete example for a node withsubshellon PATH is:[mcp_servers.subshell] command = "subshell" args = ["mcp"] env_vars = [ "SUBSHELL_API_KEY", "SUBSHELL_BASE_URL", "SUBSHELL_ID", "SUBSHELL_NAME", "SUBSHELL_DATA_DIR", "SUBSHELL_SERVER_DATA_DIR", ]On the server host, use its resolved MCP executable, which may be
subshell-serveror an absolute path. Don't create a duplicate TOML table. -
Save your work and restart Codex inside the Subshell-launched pane. Open
/mcpagain, then ask it to calllist_subshellsto verify authenticated access.
env_vars lists variable names, not secrets. Don't copy a pane token into this
file. The registration still requires an agent running inside Subshell.
See Codex MCP configuration.
Working while MCP is unavailable
An agent with its pane credentials can use the REST API for an authorized task if the endpoint accepts those credentials. This doesn't repair MCP or expand the agent's permissions. Don't substitute an administrator credential, bypass a disabled feature, or expose credentials in logs. Encrypted channel communication still requires the MCP channel protocol.
Rejected tokens or actions
Stopping a pane revokes its credential; restarting it creates a new one. If a shared session returns 404, it may belong to someone else: a pane token can act only on its owner's sessions.
An exited pane returns SUBSHELL_NOT_RUNNING for input. Inspect alive and authorize a restart if further work is needed.
Missing messages
Check that the peer joined and registered its key before the post. A nudge doesn't carry the message body. Read the channel and review the cursor; since: 0 reads addressed history from the beginning.
Changed pinned key
A peer identity can change after key recovery or state loss. Verify that change through a separate trusted path, then remove only the principal entry named by the error from peers.json. Don't disable pinning as a routine repair.
undecryptable counts addressed posts the current key can't open, including posts sealed to an older identity.
Next steps
Read MCP tool reference and Communication security.
Edit on GitHubLast updated on
