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 eight tools. Six 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 eight tools will appear in the available tool list. Use get_version to confirm the connection and edition.

04 Configuration

The server reads aishell-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

05 Standard Edition Tools

These six tools are available in both Standard and Enterprise editions. All edition detection is automatic — the server calls --version on both binaries at startup and caches the result.

06 Enterprise Edition Tools

These two tools 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 before attempting enterprise tools.

07 Common Workflows

First Connection

Running a Safe Plan

Debugging a Policy Denial

Authoring and Testing a Policy Override

08 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.

09 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

Evaluation copies of AIShell-Gate write a banner to stdout before the JSON response — for example, an expiry warning such as "Evaluation copy — expires in 23 days." If this 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 was added not because the binaries misbehave, but because future binary versions, custom builds, or deployment scenarios could introduce preamble text in stdout without the MCP developer expecting it. The guard 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 four 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
• dump_policy — on the --dump-policy 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.

10 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-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-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.

dump_policy returns "not available in standard edition"

The installed binary is the Standard edition. dump_policy and verify_audit_log require the Enterprise edition binary. 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.

11 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.