How to Install and Run SkillSpector as an MCP Server

SkillSpector exposes its security scanning pipeline as a Model Context Protocol (MCP) server via the skillspector mcp command, enabling MCP-capable agents to evaluate skills before installation using stdio or HTTP transport.

SkillSpector is NVIDIA’s open-source security scanner for AI skills. Running it as an MCP server allows Claude Code, Codex CLI, and other MCP-compatible agents to invoke the scan_skill tool directly, integrating automated safety checks into your development workflow. The server implementation in src/skillspector/mcp_server.py wraps the standard scanning engine with a FastMCP interface, supporting both local stdio and remote HTTP transports.

Installing the MCP Extra

The core SkillSpector package does not include MCP support by default. You must install the optional mcp extra to pull in the fastmcp dependency declared in pyproject.toml.

Using uv (Recommended)

uv provides the fastest installation and seamless updates:

uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/SkillSpector.git'

Update later with:

uv tool update skillspector

Using pip

If you prefer pip, use this command:

pip install "skillspector[mcp] @ git+https://github.com/NVIDIA/SkillSpector.git"

Verify the installation by checking for the mcp sub-command:

skillspector --help

Running the MCP Server

The mcp sub-command is defined in src/skillspector/cli.py (lines 43-78). It initializes a FastMCP instance from src/skillspector/mcp_server.py and registers the scan_skill tool, which executes the standard SkillSpector analysis graph and returns findings in JSON, Markdown, or SARIF format.

stdio Transport (Local Agents)

The default stdio transport communicates over standard input and output streams, making it ideal for local CLI agents that launch SkillSpector as a subprocess:

skillspector mcp

When running in this mode, FastMCP reads JSON-RPC requests from stdin and writes responses to stdout. Agents like Claude Code can call the scan_skill tool directly through this pipe.

HTTP Transport (Remote Access)

For remote agents or A2A (Agent-to-Agent) workflows, launch the server with HTTP transport:

skillspector mcp --transport http --host 0.0.0.0 --port 8080

By default, the HTTP server binds to 127.0.0.1:8000. The example above exposes it on all interfaces at port 8080. Remote callers can POST to http://localhost:8080/scan_skill with a JSON payload containing the skill path and desired output format.

Architecture and Implementation Details

The MCP server implementation resides in src/skillspector/mcp_server.py, which constructs a FastMCP server and registers the scan_skill tool. When invoked, this tool creates a scan state using the same options as the skillspector scan command, runs the analysis graph, and returns results.

Key implementation details:

• Entry point: The mcp function in src/skillspector/cli.py (lines 44-78) parses --transport, --host, and --port arguments before delegating to the server runner.
• Exit codes: The server exits with a non-zero status if the highest risk score exceeds the configured threshold, enabling CI pipelines to reject unsafe skills automatically.
• Dependency handling: If the mcp extra is not installed, the CLI prints a clear error and exits with code 2.

Practical Usage Examples

Call the scan_skill Tool via HTTP

With the HTTP server running on port 8000:

curl -X POST http://127.0.0.1:8000/scan_skill \
     -H "Content-Type: application/json" \
     -d '{"path":"./my-skill/","format":"json"}'

Programmatic Server Startup

Start the server from Python code for embedded workflows:

from skillspector.mcp_server import run as run_mcp

# Launch HTTP transport on localhost:9000

run_mcp(transport="http", host="127.0.0.1", port=9000)

Integration with FastMCP CLI

For stdio mode, you can interact with the server using the FastMCP CLI (available when fastmcp is installed):

# Terminal 1: Start the server

skillspector mcp

# Terminal 2: Send a request

printf '{"tool":"scan_skill","input":{"path":"./my-skill/","format":"json"}}\n' | fastmcp

Summary

• Install the MCP extra using skillspector[mcp] via uv or pip to acquire the fastmcp dependency.
• Choose your transport: use stdio (default) for local subprocess communication or http for remote network access.
• Run the server with skillspector mcp, optionally specifying --host and --port for HTTP mode.
• Access the tool: the scan_skill endpoint accepts skill paths and returns security findings in multiple formats.
• References: implementation lives in src/skillspector/mcp_server.py and src/skillspector/cli.py (lines 43-78), with extras defined in pyproject.toml.

Frequently Asked Questions

What is the difference between stdio and HTTP transport in SkillSpector MCP?

stdio (the default) communicates over standard input/output streams, making it perfect for local agents that spawn SkillSpector as a child process. HTTP exposes a REST endpoint (default 127.0.0.1:8000) that remote agents or services can reach over the network, enabling distributed A2A workflows.

What happens if I try to run the MCP server without installing the optional dependency?

The CLI checks for the mcp extra before launching. If fastmcp is missing, skillspector mcp prints a clear error message and exits with code 2, directing you to reinstall with the [mcp] extra.

Can I use SkillSpector MCP in CI pipelines to block unsafe skills?

Yes. The server exits with a non-zero status code when the scanned skill exceeds the configured risk threshold. This behavior allows you to wrap skillspector mcp in CI scripts that automatically reject pull requests containing high-risk skills, similar to the standalone scan command behavior.

Which MCP clients are compatible with SkillSpector?

Any MCP-compliant client can connect, including Claude Code, Codex CLI, Gemini CLI, and custom implementations using the MCP SDK. The scan_skill tool uses standard JSON-RPC over stdio or HTTP/SSE, following the Model Context Protocol specification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}