Preface¶
In the DSH ecosystem, MCP servers usually declare their capabilities at runtime, rather than predefining them through a manifest, package.json fields, or schema files. As a result, the only way to know what a server can do is to start it—and starting it is itself a trust decision. Most clients establish trust once at installation time and then never revisit it.
This creates three concrete problems: each npx -y run fetches the latest version, the actual capabilities of tools are not visible in the descriptions, and the server receives the entire environment by default, including all environment variables, tokens, and sessions. mcp-cap is a DSH plugin that inspects the declared capability surface of an MCP server, seals it into a reviewable lock file, and notifies you when a version change introduces new capabilities.
Plugin Overview¶
mcp-cap is a DSH plugin focused on administrator security and supply-chain security.
- Positioning: Audits and locks the capability surface of MCP servers, preventing unauthorized privilege escalation.
- Maintainer: liyixuan201211.
- Category: admin-security.
- License: MIT.
- Core value: It does not invoke any tool (it rejects
tools/call,resources/read, andprompts/get), provides the server with only a minimal environment by default, and never prints or writes environment variable values into the lock file.
Core Features¶
The plugin implements security isolation and auditing in the following ways:
- Rejects tool execution: It uses an allowlist to reject methods such as
tools/call,resources/read, andprompts/get, ensuring that no tool is actually executed. - Minimal environment principle: By default, it does not pass full values such as
PATH,HOME, or temporary directories unless explicitly enabled with--inherit-env. This prevents the server from accessing the user’s sensitive credentials. - Capability sealing: It writes the server’s declared capability surface to a lock file, creating a committable audit record.
- Change detection: It detects changes in the capability surface with
verifyand returns different exit codes based on severity.
Install and Enable¶
Install the plugin in a DSH environment:
dsh plugin --profile web add github:liyixuan201211/mcp-cap
After installation, you can use the mcp-cap command-line tool.
Typical Usage¶
After installation, you can use the following commands to interact with an MCP server.
Inspect the declared capabilities of a server:
mcp-cap inspect -- npx -y @modelcontextprotocol/server-filesystem /srv
Seal the current capability surface:
mcp-cap seal --out .mcp-cap/fs.lock.json -- npx -y @modelcontextprotocol/server-filesystem /srv
Verify whether the capability surface has changed:
mcp-cap verify --lock .mcp-cap/fs.lock.json -- npx -y @modelcontextprotocol/server-filesystem /srv
View the environment variables that the server will receive:
mcp-cap env -- npx -y @modelcontextprotocol/server-filesystem /srv
Exit Codes and Behavior¶
The verify command conveys audit results through exit codes. The core exit code definitions are:
| Exit code | Meaning |
|---|---|
| 0 | Operation succeeded, or verify detected no change in the capability surface |
| 1 | Unexpected error |
| 2 | Usage error |
| 3 | verify detected a change in the capability surface, but it was not an escalation |
| 4 | verify detected an escalation to dangerous capabilities |
| 5 | Indeterminate: the server did not start, did not respond to MCP, or a protocol error occurred |
| 6 | Operation denied: no comparable lock file exists, or there is nothing worth sealing |
Exit code 5 means that the server state cannot be determined (for example, the server did not start or did not respond to the MCP protocol). This is never equivalent to “no capabilities found.” In addition, the plugin infers capabilities from declarations only and does not actually execute tools; this means a server might still perform malicious actions in ways not mentioned in its schema, which may not necessarily be detectable by static analysis alone.
Use Cases and Notes¶
- Use cases: Supply-chain security auditing of MCP servers, enforcing the principle of least privilege, and tracking capability changes caused by server version updates.
- Environment requirements: Compatible with DSH versions
>=0.1.5-rc.1 <0.2.0. - Permission note: The plugin runs with the permissions of the current DSH process; review the source code and license before installing.
By following the steps above, you can lock the capability surface of an MCP server and remain alert to permission changes in later runs by using verify.
Learn more from the GitHub repository or the community directory.