Using the MCP
aishell-gate-mcp — Reference and Manual

01 What the MCP Does

The AIShell-Gate MCP server is a Python stdio process that translates MCP tool calls from an AI coding environment into subprocess invocations of the two AIShell-Gate binaries. It has no policy logic of its own. It does not execute commands on its own. It is a structured bridge between the AI agent and the existing policy and execution architecture.

The server exposes eleven tools. Nine are available in both Standard and Enterprise editions. Two require Enterprise. The AI agent calls get_version on first connection to discover which tools are available and which edition is installed.

02 The Plan Model — Rebuilding the Reflex

If you have arrived at this section because the plan model is not clicking, you are in good company. The program's most common point of confusion is not the policy layer, the audit chain, or the two-binary split — those land quickly. The confusion is more fundamental: a decades-old reflex about how AI agents work with Unix is silently breaking, and it is not always obvious that it is the reflex that is wrong.

This section is written bluntly. It is here to name the reflex, show you why it fails, and replace it with a mental model that fits what the system actually does.

The Reflex That Fails You

Every other MCP server you have used follows the same shape. The server exposes a list of capability-shaped tools: write_file, read_file, edit_file, list_directory, run_command. The AI calls them one at a time. Each call does one small thing. Composition is the AI's responsibility — it strings the calls together in whatever order makes sense.

When you open AIShell-Gate's MCP and see only evaluate_plan and execute_plan, your reflex is to look for the file-writing tool. You scan the tool list again. You check the documentation for what you must have missed. You start to suspect something is wrong with the installation.

Nothing is wrong with the installation. The reflex is the problem. There is no write_file tool because AIShell-Gate is not a filesystem MCP. It is a policy-gated execution MCP that happens to be able to affect files as a side effect of running commands. Those are different categories of thing, and conflating them is where understanding breaks down.

Why the Reflex Is Worth Unlearning

The reflex comes from a real tradeoff in how existing tools were designed. A capability-shaped MCP server is easy to use safely because it is narrow. write_file can only write files. It cannot escalate privilege, spawn a shell, or touch the network, because the tool surface simply does not expose those things. Safety comes from what the tool cannot do.

AIShell-Gate takes the opposite approach. It exposes the whole operating system as a submission surface and derives safety from what the policy will allow, not from what the tool surface can address. This is a more powerful model — a single MCP can govern anything the OS can do — but it requires you to think in commands and policy, not in capabilities and tools.

The payoff is that you stop building bespoke MCP servers for every capability you want to expose. One MCP, one policy file, one audit chain, and the AI can do anything you are willing to permit. The cost is that you have to think about the system the way a Unix operator thinks about it: in commands and their effects, with a deterministic policy as the gate.

The Constraints That Define the Model

Before showing what the model can do, it helps to be explicit about what it cannot do. These constraints are not limitations to work around — they are the definition of the model. Every one of them exists because allowing it would reintroduce the attack surface the gate is built to eliminate.

These nine constraints are the mental model. Internalise them and the rest of the system's behaviour follows.

The Model You Should Build Instead

Three analogies that capture the plan model better than "MCP tool":

A plan is a CI job submission, not a terminal session. When you push a commit to a CI server, you are submitting a declarative description of work to be done. The CI server evaluates it against rules (branch protections, required reviewers, merge policy), requires approvals where necessary, runs the job, and produces an immutable record. You do not ssh into the runner and vim a file. You submit a job; the job runs. AIShell-Gate is the same shape, scaled down to the individual command level.

A plan is a signed transaction, not an API call. A database transaction is atomic: a group of operations that either all succeed under the committed rules or all fail together. You cannot reach into the middle of a transaction and change it based on intermediate state. A plan is the same. All the confirmations are collected before any action runs; once execution starts, the plan proceeds deterministically or stops cleanly.

A plan is a work order, not a conversation. When you hand a work order to a contractor, it specifies the goal and the sequence of tasks. If the contractor discovers midway that the plan does not fit the site, they do not improvise — they come back and get a new work order. That is exactly the plan segmentation pattern. Work requiring intermediate judgment is split across multiple plans, with the calling environment reading results and submitting the next plan.

Worked Examples of the Reflex Failing

The fastest way to build the new model is to see the old reflex fail against specific tasks and see what the right answer looks like.

Task 1 — "Write a Dockerfile"

The failing reflex. You reach for a write_file tool that does not exist, then try:

# Plan action — this will be denied at evaluation
{"cmd": "echo 'FROM python:3.11' > Dockerfile"}

The policy engine rejects this at step 1 of evaluation, before any rule lookup. > is a shell metacharacter. There is no shell, so the character has no meaning the executor can honour. The action is denied with a parse-level error.

The model-fit answer. There are three idiomatic approaches. All of them work because none of them need a shell:

1. Stage the file outside the gate, then place it with a command. The AI writes the Dockerfile to a staging location it already controls (its own working directory, a scratch mount, a git checkout it has direct access to). The plan contains a single cp or mv command to place it in the target location. Policy evaluates cp ./staging/Dockerfile ./Dockerfile like any other file operation — subject to writable_dirs, confirmation level, and audit record.
2. Commit to version control, pull through the gate. The AI commits the Dockerfile to a branch it already has access to outside the gated environment. The plan runs git pull or git checkout. The writing happens in git; the gate is only involved in the pull. This is the most common real-world pattern.
3. Use install or cp with a pre-written source file. If the Dockerfile content is reproducible (a template with no per-run variation), keep it in a known location and install -m 0644 /path/to/Dockerfile.template ./Dockerfile. One command. No shell. Fully auditable.

Task 2 — "Check if the build passed, then deploy"

The failing reflex. You reach for the conditional:

# Plan action — this will be denied
{"cmd": "make test && ./deploy.sh"}

&& is a shell metacharacter. Denied at parse.

The model-fit answer. Plan segmentation. Submit plan A, read its result in your orchestration code, then submit plan B based on what came back:

# Plan A — run the test
{"goal": "run test suite", "actions": [{"cmd": "make test"}]}

# Calling code inspects plan A's exit code.
# If zero, submit plan B. If not, surface the failure and stop.

# Plan B — deploy, submitted only on success
{"goal": "deploy build artifact", "actions": [{"cmd": "./deploy.sh"}]}

This is not a workaround. It is the model working correctly. Each plan is a signed transaction. Branching logic lives in the calling environment where it belongs — the Python script, the orchestration agent, the CI pipeline definition — not inside a plan where it would be hidden from policy review.

Task 3 — "Find all Python files and count their lines"

The failing reflex. The pipe:

# Denied — pipe is a metacharacter
{"cmd": "find . -name '*.py' | xargs wc -l"}

The model-fit answer. Use a single command that does the composition internally. Many Unix utilities have flags that replace common pipeline patterns:

# find with -exec: no shell, no pipe, composition done inside find
{"cmd": "find . -name *.py -exec wc -l {} +"}

This works because find spawns wc directly via its own fork/exec machinery — no shell, no pipe. The composition is semantic, not syntactic. This pattern applies broadly: grep -r instead of find | xargs grep, sort -u instead of sort | uniq, awk instead of cut | head.

What the Model Asks of You

Three habits replace the ones you are unlearning:

Think in commands, not tools. When you want to affect the system, ask "what Unix command does this?" — not "what MCP tool does this?" There is no one-to-one mapping between capabilities and tools here. The mapping is between capabilities and allowed commands under the active policy.

Move composition out of the command string. Anything that would be a pipe, a conditional, or a substitution in a shell script moves up one level — into the orchestration code that submits plans. The plan itself stays flat and declarative.

Treat each plan as atomic. A plan is not a script; it is a transaction. Compose transactions, do not embed logic inside them. The calling code decides what transaction to submit next based on what the previous one returned.

03 Installation

The MCP server is a single Python 3 script with no external dependencies. Python 3.8 or later is required. The AIShell-Gate binaries (aishell-gate-exec and aishell-gate-policy) must be installed and accessible before the server will function.

Verify Prerequisites

The --version output from the MCP server lists the protocol version, all registered tools, and which edition tools require. If the binaries are not found, the server will start but all tool calls will return structured error responses rather than crashing — making misconfiguration diagnosable from within Claude Code.

Place the Script

The MCP server can run from any directory. For system-wide availability, install it alongside the binaries:

Connect Claude Code or Cursor

Add the server to your project's .mcp.json file. The AI coding environment discovers and launches it automatically on startup.

Restart Claude Code or Cursor after adding this entry. The tools will appear in the available tool list. Use get_version to confirm the connection and edition.

Workaround — Claude Code does not load the server on restart

On some Claude Code versions the server in .mcp.json is not picked up on restart. The aishell-gate tools never appear in the tool list, and no error is reported — the entry is simply ignored. Restarting repeatedly does not resolve it.

The workaround is to force Claude Code to re-read its project configuration by making an actual edit to .claude/settings.json and saving it:

Create the file if it does not exist, or add a line to it if it does, then save and restart. The tools should then appear. get_version is a good first entry to add — it is the tool you will use to confirm the connection anyway, and §04 lists the full set worth allowing.

04 Reducing Confirmation Prompts

Two independent confirmation layers can apply to every MCP tool call. By default, Claude Code asks for approval before calling any MCP tool — including evaluate_plan, which never executes anything. Separately, AIShell-Gate's own policy engine assigns a confirmation level (none, plan, action, or typed) to every allowed action. These two layers stack: a single-command plan with no policy-level confirmation requirement can still produce a Claude Code approval prompt, because Claude Code does not know in advance that the gate would have allowed it without confirmation.

For operators who want a single, predictable confirmation surface — the gate's own policy engine, and nothing else — Claude Code's tool-approval layer can be turned off for AIShell-Gate specifically.

Option A — CLI flag, per-launch

This auto-approves every aishell-gate tool call for the current Claude Code session. It does not persist — the flag must be passed each time Claude Code is launched.

Option B — project settings file, persists automatically

Place the following at .claude/settings.json in the project root:

Restart Claude Code after adding or editing this file — permission settings are not re-read mid-session.

Scope is per-project: this file only affects the project it sits in. For the same behavior across every project, place an identical file at ~/.claude/settings.json instead.

Going further — removing native shell access entirely

The settings above remove Claude Code's approval prompt for AIShell-Gate's own tools, but they do not change what Claude Code can do. Claude Code's native Bash tool remains available alongside the gate's tools, and Claude may use either one — for a trivial command like ls, it will often reach for the native tool simply because it is the lower-friction option. For a security or policy gate, an optional gate is a significantly weaker guarantee than a mandatory one.

Two levels of enforcement are available, depending on how strict the deployment needs to be:

Soft (instruction-level, not enforced). Add a line to the project's CLAUDE.md:

This nudges Claude's tool choice but does not remove the option. Claude can still fall back to native Bash, particularly for commands that look trivial.

Hard (actually enforced). Add a deny rule for the native Bash tool in .claude/settings.json, alongside the allow list above:

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

05 Configuration

The server reads aishell-gate-mcp.json from the working directory, or from the path given via --config. All fields are optional. A missing file is not an error — defaults are used throughout.

Field Reference

06 Standard Edition Tools

These five core standard tools are documented in detail below. Two more Standard tools — run and install_engine — are summarised in §01. All edition detection is automatic — the server calls --version on both binaries at startup and caches the result.

07 Relay Confirmation & Enterprise Tools

This section covers two different tool groups. confirm_action and get_execution_result are available in both editions, but only do anything once confirm_mode: "relay" is configured — see §05. They play no role in plan_only mode, and none in operator_pipe mode either: execute_plan blocks and returns directly there, so there is nothing pending for either tool to act on. verify_policy and verify_audit_log require the Enterprise edition binary; calling them on a Standard installation returns a clear structured error — not a crash or silent failure — mirroring the binary's own behaviour. Call get_version first to confirm edition and which tools are meaningful before attempting any of these.

Relay confirmation tools — both editions

Enterprise-only tools

08 Common Workflows

First Connection

Running a Safe Plan

Running a Plan with Human Confirmation (Relay Mode)

Running a Plan with Human Confirmation (Operator Pipe Mode)

Debugging a Policy Denial

Authoring and Testing a Policy Override

09 Plans as an Alternative to Shell Scripting

A shell script is a sequence of commands toward a goal. So is an AIShell-Gate plan. The difference is everything that happens between the commands and the kernel.

A shell script carries implicit trust — whoever wrote it is assumed to have gotten it right. There is no policy layer, no risk assessment, no mandatory confirmation, and no tamper-evident record of what ran. The script and the shell are a single execution path with nothing in between.

When an AI builds a plan and submits it through the MCP, the structure is the same — a sequence of commands toward a stated goal — but the execution path runs through the policy engine first. Every command is evaluated, risk-scored, assigned a confirmation level, and logged before a single byte reaches the kernel. The AI is doing what a script author does. The environment is fundamentally different from what a shell provides.

Where Plans Are Better

A plan submitted through evaluate_plan is inspectable before it runs. The goal is stated, every action is listed, and the policy engine's assessment of each one is available before the operator commits to execution. A shell script is opaque until it runs.

Policy is external and declarable. A shell script embeds its own permissions implicitly — whatever the executing user can do, the script can do. An AIShell-Gate plan runs against a declared policy stack that is versioned, auditable, and independent of the plan itself. The same plan submitted under a stricter policy produces a different outcome without changing a line of the plan.

The audit record is tamper-evident. Shell history is not. In the Enterprise edition, every plan evaluation and execution is HMAC-chained — a verifiable record that cannot be silently modified after the fact.

Confirmation gates are structural. A destructive shell script runs. A plan with a destructive action stops at the appropriate confirmation level and requires explicit operator acknowledgement before proceeding. The gate is not advisory — it is enforced by the executor.

Where Shell Scripts Are Still Better

Shell scripts compose. They pipe the output of one command into the input of the next. They branch on exit codes. They loop. They handle intermediate state inline. A shell script that checks the output of git status before deciding whether to run git push is straightforward to write and straightforward to read.

The plan model is sequential and flat. Commands in a plan are evaluated independently — there are no conditionals, no loops, no pipes, and no shell metacharacters. Each command is a discrete action. For workflows that depend on intermediate output to decide what to do next, the plan model does not replace a shell script. The right approach in those cases is to break the workflow into plan segments, evaluate intermediate results in the calling environment, and submit subsequent plans based on what was returned.

The Adoption Angle

For teams already using Claude Code to generate shell commands, the MCP path requires no change in how they think about the problem. The AI still proposes a sequence of commands toward a goal. The difference is that the sequence now passes through a policy gate, gets confirmed at the appropriate level, and produces an audit record. The cognitive model is identical. The execution environment is safer.

10 The Preamble Guard

All binary stdout is scanned for the first { character before JSON parsing. Any text that precedes the opening brace is silently discarded. This is called the preamble guard.

Why it exists

A binary could in principle write text to stdout before its JSON response — for example, a warning banner from a future version, a custom build, or an unusual deployment scenario. If any such text precedes the JSON object, a naive json.loads(stdout) call will fail with a parse error, making the MCP server appear broken when the binary is working correctly. The guard exists as defensive programming against that possibility, not because the current binaries write any such preamble — it makes the server resilient regardless of what a binary writes before its JSON output.

How it works

Where it is applied

The guard runs at three points — every location where the server calls json.loads() on binary stdout:

• evaluate_plan — on the --dry-run-json output from aishell-gate-exec
• execute_plan — on the pre-flight --dry-run-json output before live execution
• evaluate_command — on the --json output from aishell-gate-policy

The get_policy_template tool is not subject to the guard because it already scans for the first { line by design — the template output has a documented plain-text header block before the JSON body.

What the error looks like

If the guard finds no { in the binary output at all, it returns a structured error response rather than crashing:

This makes the failure diagnosable from within Claude Code without inspecting server logs. The stderr snippet in the message typically reveals whether the issue is a missing binary, a license problem, or an unexpected runtime error.

11 Troubleshooting

Edition shows as "unknown"

The server could not find or run one of the binaries at startup. Check that exec_binary and policy_binary in aishell-gate-mcp.json point to the correct locations, or that both are on PATH. Run each binary with --version directly to confirm they are executable.

All tool calls return "binary not found"

The binaries are not reachable from the working directory the MCP server started in. Use absolute paths in aishell-gate-mcp.json rather than relative paths, or install the binaries to a system PATH location.

evaluate_plan returns "exec produced no output"

The executor ran but wrote nothing to stdout. This usually means a startup security check failed — the binary refuses to run as root, or the binary itself has setuid or setgid bits set. Check the stderr field in the error response for the specific check that failed.

execute_plan is blocked with "confirmation_required"

One or more commands in the plan require confirm level action or typed. These cannot be satisfied through the MCP interface. Options: lower the confirm level for the specific commands in a policy override file, break the plan into smaller pieces that exclude those commands, or run the high-risk commands manually at the terminal.

verify_audit_log reports a broken chain

The audit log has been modified, truncated, or reordered since it was written. If you are using an ephemeral key (no audit_key configured), cross-session verification is not possible by design — each session generates its own key. For reliable cross-session verification, configure a persistent audit_key file before the first session that should be verifiable.

Enterprise tools return "not available in standard edition"

The installed binary is the Standard edition. verify_policy and verify_audit_log require the Enterprise edition binary. Call get_version to confirm which edition is installed before attempting either of them. Contact www.aishellgate.com for Enterprise licensing.

Server does not appear in Claude Code after adding to .mcp.json

Claude Code must be restarted after changes to .mcp.json. Ensure the Python 3 interpreter path is correct and that the script is executable. Run the server manually in a terminal to confirm it starts without error: python3 /path/to/aishell-gate-mcp --version.

Enabling debug logging

Pass --debug to the server to enable verbose stderr logging. In Claude Code, stderr from MCP servers is typically available in the developer console or log output. Debug output includes binary invocations, response sizes, preamble strip events, and edition detection results.

12 Edition Summary

Run get_version to identify the installed edition. Calling an Enterprise tool on a Standard installation returns a structured error response with a clear message and a link to licensing information — not a crash or an unknown error.