How to Use SkillSpector as an MCP Server: Complete Setup Guide

SkillSpector can be run as a Model Context Protocol (MCP) server by installing the optional [mcp] extra and running the skillspector mcp command, which exposes the scan_skill tool for AI agents to evaluate skills before installation.

NVIDIA/SkillSpector provides a Model Context Protocol (MCP) server implementation that enables AI agents to programmatically scan skills for security risks. When you run SkillSpector as an MCP server, it exposes the scan_skill tool over stdio or HTTP transports, allowing seamless integration with Claude Code, Codex CLI, and other MCP-capable clients.

Architecture Overview

The SkillSpector MCP server implementation is split across two key modules. The src/skillspector/mcp_server.py module builds a FastMCP server instance and registers the scan_skill tool, which internally executes the standard SkillSpector analysis pipeline. The src/skillspector/cli.py module (lines 44-78) provides the mcp subcommand that parses transport options—stdio or http—and launches the server with the appropriate configuration.

When a request is received, the server creates a scan state using the same options as the normal skillspector scan command, invokes the analysis graph, and returns findings in JSON, Markdown, or SARIF format. 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.

Installation Requirements

The core SkillSpector package does not ship with MCP dependencies. You must install the optional [mcp] extra, which pulls in the fastmcp package required for the server implementation.

Installing the MCP Extra

Use uv (recommended) or pip to install with MCP support:

# uv - CLI-only installation

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

# Later updates

uv tool update skillspector

# pip - if you prefer pip

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

Verify the installation by checking for the mcp subcommand:

skillspector --help

The mcp feature is declared in pyproject.toml under the optional dependencies section.

Running SkillSpector as an MCP Server

The skillspector mcp command starts the server. By default, it uses stdio transport for local agent communication, but you can switch to HTTP for remote access.

Standard I/O Transport (stdio)

The stdio transport (default) is ideal for local CLI agents that launch SkillSpector as a subprocess. FastMCP communicates over standard input and output streams.

skillspector mcp

This starts a FastMCP server that reads commands from stdin and writes responses to stdout. Agents can invoke the scan_skill tool directly through this interface.

HTTP Transport

For remote callers or A2A (Agent-to-Agent) workflows, use the HTTP transport. The default host is 127.0.0.1 and the default port is 8000.

# Bind to all interfaces with custom port

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

The server listens on http://0.0.0.0:8080/ and accepts POST requests from remote agents.

Calling the scan_skill Tool

Once the SkillSpector MCP server is running, you can invoke the scan_skill tool using either transport method.

Using stdio with FastMCP CLI

In one terminal, start the server:

skillspector mcp

In another terminal, send a request using the FastMCP CLI:

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

HTTP Endpoint Requests

When running in HTTP mode, send a POST request to the /scan_skill endpoint:

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

The server returns the analysis results in the requested format (JSON, Markdown, or SARIF).

Programmatic Server Integration

You can also start the MCP server programmatically from Python for advanced use cases:

from skillspector.mcp_server import run as run_mcp

# Run the server on localhost:9000 using HTTP transport

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

This imports the run function from src/skillspector/mcp_server.py and starts the server with your specified configuration.

Summary

• Install with MCP support: Use uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/SkillSpector.git' or the equivalent pip command to get the fastmcp dependency
• Start the server: Run skillspector mcp for stdio transport or skillspector mcp --transport http --host 0.0.0.0 --port 8080 for HTTP access
• Tool availability: The server exposes the scan_skill tool via FastMCP as implemented in src/skillspector/mcp_server.py
• Output formats: Returns findings in JSON, Markdown, or SARIF formats
• CI integration: Exits with non-zero status when risk thresholds are exceeded, enabling automated rejection of unsafe skills in pipelines

Frequently Asked Questions

What transport options does the SkillSpector MCP server support?

The SkillSpector MCP server supports two transport modes: stdio (default) for local subprocess communication via standard input/output streams, and HTTP for remote access via a lightweight web endpoint. The transport is configured using the --transport flag in the skillspector mcp command defined in src/skillspector/cli.py.

How do I install the MCP dependencies for SkillSpector?

You must install the optional [mcp] extra when installing SkillSpector. Use uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/SkillSpector.git' or pip install "skillspector[mcp] @ git+https://github.com/NVIDIA/SkillSpector.git". If the dependency is missing, the CLI prints a clear error and exits with code 2 when attempting to run the MCP server.

Can I use SkillSpector as an MCP server in CI/CD pipelines?

Yes. When running as an MCP server, SkillSpector exits with a non-zero status code if the highest risk score from a scan exceeds the configured threshold. This behavior allows CI pipelines to automatically reject unsafe skills by checking the exit code after invoking the scan_skill tool, whether through stdio or HTTP transport.

What tool does the SkillSpector MCP server expose?

The SkillSpector MCP server exposes a single tool called scan_skill. This tool is registered in the FastMCP server instance within src/skillspector/mcp_server.py and executes the standard SkillSpector analysis pipeline, accepting parameters for the skill path and output format.

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