AISHELL-GATE --  MCP INTEGRATION README 
===================================================================================
copyright (2026) AIShell Labs LLC. Winston Salem NC USA.

This covers installing AIShell-Gate's MCP server for Claude Code (MCP
stands for Model Context Protocol -- the standard that lets Claude talk to
external tools and servers like this one), plus three optional follow-on
configurations: reducing confirmation prompts, fully replacing Claude
Code's native shell access with the gate, and running the server under a
different MCP client.

More complete documentation can be found in the HTML guide 
AIShell_Gate_USING_MCP.html

Sections 1-3 are written for Claude Code, which is the client AIShell-Gate
has been tested with. The MCP server itself is a standard stdio MCP server
and is not Claude-specific -- see section 4 if you are using Cursor, VS
Code, Windsurf, Claude Desktop, or Zed.



1. INSTALL
-----------

USE AISHELL-GATE-INSTALL.SH TO AUTOMATICALLY INSTALL EVERYTHING 

==== OR DO THE FOLLOWING =======

1. Install the 4 AIShell-Gate executable files to /usr/local/bin (a standard,
   system-wide folder that command-line programs are often installed
   into; writing to it usually requires administrator permission, i.e.
   running the copy command with sudo in front of it):
     cp aishell-gate aishell-gate-exec aishell-gate-policy aishell-gate-mcp  
	/usr/local/bin
     

   aishell-gate-mcp looks for aishell-gate binary in the following manner
 and order: 

  `  0. the absolute path set in aishell-gate-mcp.json
     1. The AISHELL_EXEC_BIN / AISHELL_POLICY_BIN environment variables,
        if you've set them. (An environment variable is a named value you
        can set in your terminal that a program can read on startup.)
     2. ~/.local/share/aishell-gate/bin -- a fixed folder in your own user
        account, and the folder the install_engine tool (described just
        below) automatically places binaries into.
     3. /usr/local/bin -- the shared, system-wide folder from step 1
        above.
     4. The current working directory -- whatever folder you happen to be
        running the command from.
     5. Your PATH -- the list of folders your operating system
        automatically searches whenever you type a command by name.

   If the mcp server is loaded and run by a client and the backend 
aishell-gate engine is not found the mcp will try to use its own internal
installation process to download and install aishell-gate backend and place 
it in ~/.local/share/aishell-gate/bin -- no sudo required. 
Either the manual
   
2. Set your API key for whichever AI client you're using, e.g.:

     export ANTHROPIC_API_KEY="your-key-here"

   Add this line to your ~/.bashrc (or shell profile) if you want it set
   automatically in every new terminal session.
 
   Claude Code now allows for subscription access which does not require
an API Key. Other systems may require different access authorization.

3. Copy aishell-gate-mcp.json in your project root. This configures the
   gate itself -- things like which binaries to use, which policy preset
   to apply, and how confirmations are handled. For a first install, the
   values below are reasonable defaults; you generally don't need to
   change them to get started:

     {
       "exec_binary":        "aishell-gate-exec",
       "policy_binary":      "aishell-gate-policy",
       "preset":             "ops_safe",
       "jail_root":          null,
       "sandbox":            null,
       "policy_base":        null,
       "policy_project":     null,
       "policy_user":        null,
       "source":             "ai",
       "audit_log":          null,
       "policy_audit_log":   null,
       "audit_key":          null,
       "eval_timeout":       30,
       "input_timeout":      30,
       "max_response_bytes": 0,
       "extra_flags":        [],
       "confirm_mode":       "plan_only"
     }

   Do not add // comments to this file. The server parses it as strict
   JSON and will refuse to start if the file contains comments. The
   fields and values that require the Enterprise edition are: the
   ci_build, ci_deploy, ci_admin, and danger_zone presets; policy_base;
   policy_project; and audit_key. Everything else here works in the
   Standard edition -- including confirm_mode "relay".

4. copy dot_mcp.json to .mcp.json in your project root. Note the change from
"dot" to ".".  This is a different file from
   the one above: aishell-gate-mcp.json configures how the gate behaves,
   while .mcp.json tells Claude Code how to start the MCP server process
   in the first place. Use exactly the shipped dot_mcp.json template below
     {
       "mcpServers": {
         "aishell-gate": {
           "command": "sh",
           "args": [
             "-c",
             "if command -v aishell-gate-mcp >/dev/null 2>&1; then exec aishell-gate-mcp; else exec python3 ./aishell-gate-mcp; fi"
           ]
         }
       }
     }

   WHAT THAT LINE DOES (don't "simplify" it): this runs a small shell
   script with two possible outcomes.
     - `command -v aishell-gate-mcp` is a shell command that checks
       whether a program named aishell-gate-mcp can be found anywhere on
       your PATH (for example, the copy you installed to /usr/local/bin
       in step 1).
     - `>/dev/null 2>&1` sends any output from that check to a special
       location that discards it, so the check happens silently with
       nothing printed.
     - If the check succeeds, the script runs `exec aishell-gate-mcp`,
       launching the installed copy directly.
     - If it doesn't find one, the script falls back to
       `exec python3 ./aishell-gate-mcp`, running a copy sitting in the
       current project folder instead, through the Python interpreter.
     - `exec` matters in both branches: instead of starting the server as
       a separate child process while the shell script keeps running
       alongside it, `exec` replaces the shell script's own process with
       the server. That keeps the server's input/output connected
       directly to Claude Code with nothing in between -- keep this
       keyword in place.

   So both a standard, PATH-installed setup and a copy-in-project setup
   work from the exact same file. The python3 fallback is deliberate: a
   file copied by hand may have lost its "this file can be run directly"
   permission (its execute bit), and running it through the python3
   interpreter doesn't require that permission.
   PRECEDENCE NOTE: PATH wins over the project-root copy. If both exist --
   one installed to /usr/local/bin and one sitting in your project folder
   -- this script always runs the /usr/local/bin one.
   If your install lives somewhere else entirely, replace the whole args
   line with the absolute path form (a full path starting from the root
   of the filesystem, rather than a path relative to the current folder):
     "command": "python3", "args": ["/your/path/aishell-gate-mcp"]

   WARNING: Check for a stray .mcp.json already in your project root
   before adding this one. If one already exists with a different path,
   Claude Code will quietly use that existing one instead of showing an
   error -- this is the single most common setup issue. Always restart
   Claude Code after creating or editing .mcp.json.

5. Restart Claude Code. Run /mcp to confirm aishell-gate shows as
   connected, then ask Claude to call get_version to confirm the binaries
   are found correctly.


2. REDUCE CONFIRMATION PROMPTS (OPTIONAL)
------------------------------------------

By default, Claude Code asks you to approve every MCP tool call (every
time Claude asks AIShellGate's server to do something, such as run or
execute_plan) -- on top of any confirmation AIShell-Gate's own policy
engine separately requires. That's two separate layers of prompts
stacking on each other.

To remove Claude Code's outer layer and rely solely on AIShell-Gate's own
policy/confirm-level system, copy settings.json to .claude/settings.json.
settings.json contains the following:

     {
       "permissions": {
         "allow": [
           "mcp__aishell-gate__run",
           "mcp__aishell-gate__execute_plan",
           "mcp__aishell-gate__evaluate_plan",
           "mcp__aishell-gate__evaluate_command",
           "mcp__aishell-gate__get_version",
           "mcp__aishell-gate__get_policy_template",
           "mcp__aishell-gate__verify_policy",
           "mcp__aishell-gate__confirm_action",
           "mcp__aishell-gate__get_execution_result"
         ]
       }
     }

Notes:

  - Server name must match exactly. Each permission string follows the
    pattern mcp__{server-name}__{tool-name}. If you named your server
    something other than aishell-gate in .mcp.json, update every line
    above to match that name instead.


  - Scope is per-project. This file only affects the project folder it
    sits in. For a setting that applies globally across all your
    projects, place the same file at ~/.claude/settings.json instead.

  - settings.json does not support comments. It's parsed as strict JSON,
    which has no built-in way to add explanatory notes. If you want to
    keep notes like the ones above attached to the file, use a
    "_comment" key (unofficial, but currently tolerated) or keep notes in
    a separate document of your own.


3. MAKE AISHELL-GATE THE ONLY PATH TO THE SHELL (OPTIONAL, STRONGER)
----------------------------------------------------------------------

Steps 1-2 reduce prompts but don't change what Claude can do -- Claude
Code's native Bash tool is still available alongside AIShell-Gate's
tools, and Claude may use either one. 

There are two levels of enforcement:

SOFT (instruction-level, not enforced)

  Add to your project's CLAUDE.md:

    "Always use AIShell-Gate's run or execute_plan tool instead of
    the native Bash tool for any shell command."

  This nudges Claude's behavior but doesn't remove the option -- Claude
  can still fall back to native Bash, especially for trivial commands.

HARD (actually enforced)

  Add a deny rule for the native Bash tool in .claude/settings.json,
  alongside the allow list from Step 2:

     {
       "permissions": {
         "allow": [
           "mcp__aishell-gate__run",
           "mcp__aishell-gate__execute_plan",
           "mcp__aishell-gate__evaluate_plan",
           "mcp__aishell-gate__evaluate_command",
           "mcp__aishell-gate__get_version",
           "mcp__aishell-gate__get_policy_template",
           "mcp__aishell-gate__verify_policy",
           "mcp__aishell-gate__confirm_action",
           "mcp__aishell-gate__get_execution_result"
         ],
         "deny": [
           "Bash"
         ]
       }
     }

  This removes the native shell tool from Claude's toolset entirely.
  Claude must route any shell-like action through AIShell-Gate, or not do
  it at all.

  Before enabling this, confirm AIShell-Gate's policy engine actually
  covers every legitimate shell pattern your workflow needs -- piping,
  redirects, multi-command chains, and so on. Anything Bash could do that
  your run/execute_plan envelope can't yet express will now fail outright,
  instead of silently falling back to native Bash. The AI will be able
  to compensate by, for example, coping the output of one shell command
to the input of another shell command thereby creating a pipe or other
none allowd shell functions in a safer manner.


4. OTHER MCP CLIENTS (CURSOR, VS CODE, WINDSURF, ...)
------------------------------------------------------

  AIShell-Gate's MCP server is a standard stdio MCP server. It is not
  specific to Claude Code, and any MCP-compatible client can run it. The
  server config block itself -- the "command" and "args" from step 4 of
  INSTALL -- is identical everywhere. What differs between clients is
  only WHERE the file goes, and in two cases, WHAT THE TOP-LEVEL KEY IS
  CALLED.

  BEEN TESTED WITH: Claude Code. Other clients should work, but have not
  been verified. If you run AIShell-Gate under another client, reports are
  welcome (info@aishellgate.com).

  WHERE THE CONFIG GOES:

    Claude Code      .mcp.json in the project root
    Cursor           .cursor/mcp.json in the project root, or
                     ~/.cursor/mcp.json to apply it globally
    VS Code          .vscode/mcp.json in the project root
    (with Copilot)
    Windsurf         mcp_config.json -- easiest reached from the Cascade
                     panel: click the MCPs icon, then Configure
    Claude Desktop   macOS:   ~/Library/Application Support/Claude/
                                claude_desktop_config.json
                     Windows: %APPDATA%\Claude\claude_desktop_config.json
    Zed              Zed's settings file

  THE ONE THING THAT WILL TRIP YOU UP -- the top-level key is not the
  same in every client. Most use "mcpServers", exactly as shown in step 4.
  But:

    VS Code (Copilot)  uses  "servers"          instead of "mcpServers"
    Zed                uses  "context_servers"  instead of "mcpServers"

  Everything inside the block stays the same; only that outer key
  changes. So for VS Code the file is:

    {
      "servers": {
        "aishell-gate": {
          "command": "sh",
          "args": [
            "-c",
            "if command -v aishell-gate-mcp >/dev/null 2>&1; then exec aishell-gate-mcp; else exec python3 ./aishell-gate-mcp; fi"
          ]
        }
      }
    }

  Copying a working Claude Code or Cursor config straight into VS Code
  without renaming that key is the most common reason a server silently
  fails to appear.

  WHAT YOU DO NOT GET ON OTHER CLIENTS (yet):

    - Section 3's Bash-deny. That works by removing Claude Code's native
      Bash tool through .claude/settings.json, which is a Claude Code
      mechanism with no direct equivalent elsewhere. Other clients have
      their own permission models. Without an equivalent in place,
      AIShell-Gate is the PREFERRED path to the shell on those clients,
      not the ONLY path -- the AI may still be able to run shell commands
      through the client's own tooling, outside the gate. Treat
      AIShell-Gate as advisory rather than enforcing until you have
      configured your client's own permissions to match.

    - Section 2's permission allow-list, for the same reason. Expect more
      per-call approval prompts, or whatever the equivalent is in your
      client.

  The gate's own configuration -- aishell-gate-mcp.json in the project
  root -- is not client-specific and works unchanged everywhere. So does
  the usage guide the installer stages into your project, which any agent
  able to read a file can be pointed at.

  UI SHORTCUTS: Cursor and Windsurf both offer a UI for adding servers,
  so you may not need to hand-edit anything. In Cursor: Settings -> Tools
  & Integrations -> New MCP Server. In Windsurf: the MCPs icon in the
  Cascade panel -> Configure. Windsurf also refreshes without a full
  restart -- click Refresh in the Cascade panel after saving. Claude
  Desktop, by contrast, reads its config only at startup, so it must be
  fully restarted.


QUICK TROUBLESHOOTING CHECKLIST
--------------------------------

If a tool call hangs or returns nothing:

  - Confirm all 4 programs actually exist:
      ls -la /usr/local/bin/aishell-gate*
    (`ls -la` lists matching files along with their permissions, size,
    and other details; the trailing `*` is a wildcard that matches any
    filename starting with "aishell-gate".)

  - Confirm there's no second, stale .mcp.json elsewhere in the project
    overriding your real one.

  - Restart Claude Code after any change to .mcp.json or
    aishell-gate-mcp.json -- neither file is re-read while a session is
    already running.

 - Aske Claude Code for help. It can read files, documentation, etc. Tell
it where the docs are and that you want to install aishell-gate.

  - Validate settings.json is still valid JSON after editing:
      python3 -m json.tool .claude/settings.json > /dev/null && echo OK
    (This asks Python to parse the file as JSON. If the file is valid,
    the reformatted output is discarded and "OK" is printed; if there's a
    syntax error, Python prints a message describing it instead.)

  - If behavior doesn't match the version you think you're running,
    check for a second copy. As covered above, the resolver prefers
    ~/.local/share/aishell-gate/bin over /usr/local/bin over the project
    root, and .mcp.json's launcher prefers a PATH-installed copy over a
    project-root copy. List every possible location at once to check:
      ls -la ~/.local/share/aishell-gate/bin /usr/local/bin/aishell-gate* ./aishell-gate* 2>/dev/null
    (The trailing `2>/dev/null` hides the "no such file" errors that
    would otherwise show up for any of these locations that don't exist,
    so you only see the copies that are actually there.)

  - If the server won't start under the direct-command launcher, confirm
    the script is executable -- meaning it's marked as runnable, which
    `ls -l` shows as an "x" in the permissions column:
      ls -l /usr/local/bin/aishell-gate-mcp
    If the x is missing, run `chmod +x /usr/local/bin/aishell-gate-mcp`
    to add it.
