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

> Learn to run SkillSpector as an MCP server. This guide shows how to install the mcp extra and use the skillspector mcp command to expose the scan_skill tool for AI agents.

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

---

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

```bash

# uv - CLI-only installation

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

# Later updates

uv tool update skillspector

```

```bash

# 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:

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

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

```bash

# 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:

```bash
skillspector mcp

```

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

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

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

```python
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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) and executes the standard SkillSpector analysis pipeline, accepting parameters for the skill path and output format.