Error: Unknown MCP Tool 'run_shell' — Causes and Fixes

Quick Answer

The MCP client attempted to invoke a tool named run_shell, but no connected MCP server currently advertises a tool with that exact name. This error has nothing to do with the MCP protocol connection itself — your server may be online and healthy. The problem is that run_shell was never registered as an available tool, or the wrong server is connected, or the tool name simply does not match.

Fix it by running tools/list against your connected server, confirming run_shell actually appears, and checking the exact name. If it does not appear, the tool is not available on that server.

Unknown MCP Tool 'run_shell': 60-Second Fix Checklist

Work through this list top to bottom. Most cases resolve at step 3 or 4.

• List available tools — send tools/list or check MCP Inspector to see what tools the server actually exposes
• Confirm the correct MCP server is connected — the right server may not be the active one
• Verify the server exposes a shell tool at all — not every MCP server includes shell execution
• Check the exact tool name — the server may expose shell_exec, execute_command, bash, or something else entirely
• Restart the MCP client — tool caches go stale; a restart forces a fresh tools/list negotiation
• Inspect server logs — look for registration errors, startup failures, or capability negotiation issues
• Test with MCP Inspector — confirm what the server truly advertises independent of the client
• Check permissions or policy restrictions — some environments disable shell tools by policy
• Do not assume any MCP server can run shell commands — this capability must be explicitly built and registered

Tool Name vs MCP Method: Understanding the Distinction

This confusion trips up a lot of developers. The MCP protocol and tool names are different layers.

tools/call is the MCP protocol method. It is defined in the spec and every compliant MCP server that supports tools must implement it.

run_shell is a tool name — an application-level identifier that a specific MCP server registers. There is no requirement in the MCP specification that any server expose a tool named run_shell. It is completely server-defined.

When you see error: unknown MCP tool 'run_shell', the client successfully reached the server and called tools/call, but the server looked up run_shell in its tool registry and found nothing.

Client                        MCP Server
  |                               |
  |--- tools/call run_shell ------>|
  |                               |  (looks up 'run_shell' in registry)
  |                               |  (not found)
  |<-- error: unknown tool --------|  

This is fundamentally different from MCP Error -32601 Method Not Found, which means the server does not implement tools/call at all.

Why run_shell Is Unknown: Root Cause Table

How to Check Which Tools Are Actually Available

Using MCP Inspector

MCP Inspector is the most reliable way to verify what a server actually exposes, independent of client-side caching or UI bugs.

# Install MCP Inspector globally
npx @modelcontextprotocol/inspector

Connect to your server, then send a tools/list request from the interface. The raw JSON response tells you exactly what tool names the server advertises and what input schemas they expect.

If run_shell does not appear in the tools/list response inside MCP Inspector, it is not available. Full stop. No client-side fix will make it appear.

Via Raw JSON-RPC

If you want to verify programmatically:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Expected response structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "run_shell",
        "description": "Execute a shell command",
        "inputSchema": {
          "type": "object",
          "properties": {
            "command": { "type": "string" }
          },
          "required": ["command"]
        }
      }
    ]
  }
}

If tools is an empty array, or run_shell is absent from the list, the server does not expose it.

In Claude Desktop

In Claude Desktop, connected MCP servers and their tools are surfaced in the UI when you start a conversation. You can also check ~/Library/Logs/Claude/mcp*.log (macOS) for tool registration output during server startup.

In Cursor

Cursor exposes MCP tools through its settings panel. Open Settings → MCP and inspect which servers are connected and which tools each server advertises. If the tool list is blank or incomplete, check the Cursor developer console for errors.

Fix: Server Connected but run_shell Is Missing

A connected server that shows no shell tools is the most common scenario. Work through these sub-causes:

1. Tool Registration Failure at Startup

MCP servers register tools during initialization. If a dependency is missing or a config value is wrong, the tool may silently fail to register.

Check server logs immediately after startup. Look for:

• Error registering tool
• Tool run_shell failed to initialize
• Missing environment variables the tool depends on
• Import errors if the tool handler is in a separate module

2. Capability Negotiation

During the MCP handshake, the server declares which capabilities it supports (including tools). If your server's initialize response omits tools from capabilities, the client may never attempt tools/list.

{
  "capabilities": {
    "tools": {}
  }
}

Verify your server's initialize response includes the tools capability. If it does not, the server was not built to expose tools, regardless of what tool handlers you define.

3. Configuration Flags

Many MCP servers support configuration to enable or disable specific tools. A common pattern:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "ENABLE_SHELL_TOOLS": "true"
      }
    }
  }
}

If ENABLE_SHELL_TOOLS is missing or false, the server may intentionally skip registering shell tools. Check the server's documentation for its configuration flags.

4. Wrong Server Is Actually Connected

In multi-server setups, it is easy to assume a particular server is active when a different one is responding. Verify by checking the serverInfo field in the initialize response — it should contain the server name and version you expect.

5. Server Version Mismatch

If someone updated the MCP server package and the tool was renamed or removed, the old tool name no longer works. Run tools/list after every server update to audit for changed tool names.

Agent or Prompt Hallucinated run_shell

This is more common than most developers expect. LLM-based clients like Claude or agent frameworks can generate tool calls for tool names that were never available in the current session.

Why it happens:

• The model was trained on examples containing run_shell
• A previous session or prompt mentioned run_shell and the model carried it forward
• The system prompt described shell execution without listing actual tool names
• The agent reasoned that shell execution should be available and invented the name

How to identify it:

Run tools/list. If run_shell does not appear in the response, it was never registered. The agent called something that was never there.

Fix:

Update the system prompt to reference only the tools that actually exist. If you use a tool-calling agent framework, configure it to only expose tool names sourced directly from tools/list rather than hardcoding names.

Unknown MCP Tool vs Method Not Found

These errors look similar but require completely different fixes.

If you are seeing -32601, the problem is at the protocol level, not the tool level. See the MCP Error -32601 troubleshooting guide for that scenario.

Security Warning: Shell Execution Tools Are High Risk

Before installing any MCP server that exposes shell execution, understand what you are enabling.

What Shell Tools Can Access

• Arbitrary command execution — any command the OS user can run
• Filesystem read/write — files, configs, credentials, SSH keys
• Environment variables — API keys, tokens, database passwords
• Network access — outbound connections, exfiltration
• Process spawning — running additional programs or scripts

Minimum Requirements Before Using a Shell Tool

• Allowlist commands — the tool should only permit specific, pre-approved commands, not arbitrary input
• Sandbox the execution environment — use Docker, nsjail, or similar isolation
• Require human approval — implement an approval step before the tool executes any command
• Enable audit logging — log every invocation with the full command and requester identity
• Apply least privilege — run the server process as a restricted user with no access to sensitive paths
• Never expose on a public-facing server — shell tools should only exist in controlled, private environments

If an AI agent is automatically calling run_shell without human review, that is a serious security design problem regardless of whether the tool exists. Do not install a shell tool just to satisfy an agent that is calling it without oversight.

For a detailed breakdown of MCP security controls, see MCP security best practices.

Full Troubleshooting Table

How to Confirm the Fix

Once you believe you have resolved the issue, verify these six things before closing the investigation:

1. Correct server is connected — serverInfo in the initialize response matches the expected server name and version
2. tools/list includes the tool — run tools/list and confirm run_shell (or the actual tool name you intend to use) appears in the response
3. Exact tool name matches — the name in tools/list is character-for-character identical to the name being called; run_shell and runShell are different
4. Client can successfully invoke the tool — test a minimal call with a safe input and confirm you get a valid result, not an error
5. Approval and permission flow works — if the tool requires human approval, confirm that step triggers correctly and is not bypassed
6. Server logs show clean registration — on server startup, logs should show the tool registering without errors

You can use the MCPForge MCP server testing tool to run a structured tools/list check against your server endpoint.

Prevention: Stop This Error From Recurring

• Pin server versions — tool names can change between versions; lock the version in your package manager
• Source tool names dynamically — in agent code, populate the tool list from tools/list at runtime rather than hardcoding names
• Audit tools after every server update — run tools/list as part of your deployment checklist
• Add tools/list to your health check — a health endpoint that verifies expected tools are registered catches registration failures early
• Keep system prompts accurate — remove references to tools that no longer exist; add references to newly available tools
• Use tool allowlists in client config — explicitly declare which tools each agent is permitted to call, blocking hallucinated names by default

Official Sources

• MCP tools specification - official behavior for tools/list, tools/call, tool names, and tool errors.
• MCP Inspector documentation - official Inspector guide for testing MCP servers and tool lists.
• MCP Inspector GitHub repository - official source for the Inspector tool.

Related Reading

If this error is part of a broader MCP connectivity problem, these guides cover adjacent failure modes:

• MCP server failed to connect: causes and fixes — when the server itself is unreachable
• MCP Error -32601 Method Not Found — when the protocol method is missing entirely
• How to secure an MCP server — security controls for production MCP deployments
• MCP Inspector complete guide — in-depth walkthrough of using Inspector for diagnostics