# How to Install and Run SkillSpector as an MCP Server

> Install and run SkillSpector as an MCP server. SkillSpector security scanning pipeline enables MCP agents to evaluate skills before installation via stdio or HTTP transport.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-07-11

---

**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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/pyproject.toml).

### Using uv (Recommended)

**uv** provides the fastest installation and seamless updates:

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

```

Update later with:

```bash
uv tool update skillspector

```

### Using pip

If you prefer **pip**, use this command:

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

```

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

```bash
skillspector --help

```

## Running the MCP Server

The `mcp` sub-command is defined in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) (lines 43-78). It initializes a FastMCP instance from [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/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:

```bash
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:

```bash
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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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:

```bash
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:

```python
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):

```bash

# 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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) and [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) (lines 43-78), with extras defined in [`pyproject.toml`](https://github.com/NVIDIA/SkillSpector/blob/main/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.