MCP Risk Inventory

MCP Risk Inventory is a dependency-free Node CLI and GitHub Action for small engineering teams adopting AI coding tools. It scans common MCP/client config files and reports concrete risks before they become invisible local execution paths.

The MVP focuses on risks teams can act on immediately:

• local stdio executables that run with developer or CI permissions
• unpinned npx, pnpm dlx, yarn dlx, bunx, uvx, and Docker package/image launches
• secret-like environment variables exposed to MCP servers
• broad filesystem grants such as /, $HOME, /Users/name, or C:\Users\name
• remote MCP URLs and SSE/HTTP endpoints
• tool description or schema drift when a committed policy baseline exists
• package/registry hosts outside the default known registry list

Install

Install the CLI from npm:

npm install -g mcp-risk-inventory
mcp-risk scan .

If npm is unavailable, install the current GitHub release directly:

npm install -g github:FoundagentTest/mcp-risk-inventory#v0.1.2
mcp-risk scan .

Source repository:

https://github.com/FoundagentTest/mcp-risk-inventory

The package has no runtime dependencies and requires Node 18 or newer.

Client/Config Coverage

Auto-discovery covers common MCP/client config names in JSON, YAML, and TOML:

• repo-level files such as .mcp.json, .mcp.yaml, mcp.json, mcp.yaml, mcp.toml, mcp_config.json, mcp-settings.json, and mcp_settings.json
• Claude Desktop/Claude Code-style files such as claude_desktop_config.json, claude_code_config.json, .claude.json, and JSON under .claude/
• Cursor project configs under .cursor/
• Cline and Windsurf files such as cline_mcp_settings.json and windsurf_mcp_config.json
• VS Code MCP JSON files under .vscode/

Copilot, Gemini CLI, and internal agent setups are covered when they use these MCP-style config shapes or when you pass the config file directly:

mcp-risk scan path/to/client-config.json

If the scanner misses a client format or reports a false positive, open an issue with a redacted minimal config and the expected result.

CLI Usage

Scan the current repository with the default text report:

mcp-risk scan .

Write machine-readable JSON:

mcp-risk scan . --format json --output mcp-risk-results.json

Write SARIF suitable for GitHub code scanning:

mcp-risk scan . --format sarif --output mcp-risk-results.sarif

Fail CI on high or critical unsuppressed findings:

mcp-risk scan . --fail-on high

Generate a starter policy file with the current embedded tool description/schema hashes:

mcp-risk init . --output mcp-risk-policy.json
git add mcp-risk-policy.json

GitHub Action Usage

Use this minimal workflow when you only need job logs, a step summary, and CI failure on high findings:

name: MCP Risk Inventory

on:
  pull_request:
  push:
    branches: [main]

jobs:
  mcp-risk:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: FoundagentTest/[email protected]
        with:
          path: .
          format: text
          output: ""
          fail-on: high

Use SARIF when you want findings uploaded to GitHub code scanning:

name: MCP Risk Inventory

on:
  pull_request:
  push:
    branches: [main]

jobs:
  mcp-risk:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: FoundagentTest/[email protected]
        with:
          path: .
          policy: mcp-risk-policy.json
          format: sarif
          output: mcp-risk-results.sarif
          fail-on: high
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp-risk-results.sarif

Copyable examples live in examples/github-action-minimal.yml and examples/github-action.yml.

For local development from a checkout:

npm test
node src/cli.js scan . --format sarif --output mcp-risk-results.sarif --fail-on high

Policy Config

The scanner looks for mcp-risk-policy.json by default. A policy can:

• set the CI failure threshold with failOn
• allow known remote hosts, registry hosts, or filesystem prefixes
• accept specific findings with documented reasons
• baseline embedded MCP tool descriptions and schemas for drift detection

Example:

{
  "$schema": "./docs/policy.schema.json",
  "version": 1,
  "failOn": "high",
  "allowedRemoteHosts": ["mcp.github.com"],
  "allowedRegistryHosts": ["registry.npmjs.org", "ghcr.io", "docker.io"],
  "allowedFilesystemPaths": ["${workspace}"],
  "acceptedRisks": [
    {
      "ruleId": "MCPRISK001_LOCAL_STDIO",
      "server": "github",
      "reason": "Pinned internal wrapper reviewed by security on 2026-07-09."
    }
  ],
  "toolDescriptionHashes": {
    "github:list_issues": "sha256:..."
  }
}

Recommended workflow:

1. Run mcp-risk init . --output mcp-risk-policy.json.
2. Review every finding from mcp-risk scan . --format markdown.
3. Pin packages, narrow filesystem paths, remove literal secrets, and allow only intentional remote hosts.
4. Add narrow acceptedRisks entries only when a risk is intentional and documented.
5. Commit mcp-risk-policy.json and run the GitHub Action on pull requests.

Risk Meanings

MCPRISK001_LOCAL_STDIO means a config starts a local command. This is often expected for MCP, but it is still local code execution.

MCPRISK002_UNPINNED_PACKAGE means a package runner or Docker image can resolve to different code over time.

MCPRISK003_SECRET_ENV means a secret-like env var or literal secret is passed into an MCP server.

MCPRISK004_BROAD_FILESYSTEM means a server appears to receive broad disk access.

MCPRISK005_REMOTE_URL means a config connects to a remote MCP endpoint.

MCPRISK006_TOOL_SCHEMA_DRIFT means an embedded tool description/schema changed compared with policy.

MCPRISK007_UNKNOWN_REGISTRY means a package, image, or registry host is not in the known/allowed registry list.

Limitations

This MVP is a static scanner. It does not execute MCP servers, authenticate to registries, prove package ownership, inspect transitive dependencies, or guarantee that every client-specific config format is parsed. YAML and TOML support intentionally covers common simple config shapes rather than every language feature. Findings should be treated as review prompts and CI guardrails, not as a full security audit.