# What Is the `scan_skill` Tool in NVIDIA SkillSpector’s MCP Integration?

> Discover the `scan_skill` tool in NVIDIA SkillSpector, the core MCP endpoint for AI agents to perform secure code scans with customizable parameters like target path and LLM usage.

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

---

**The `scan_skill` tool is the core Model Context Protocol (MCP) endpoint exposed by SkillSpector that enables AI agents to execute comprehensive security scans on codebases via a standardized interface, accepting parameters like target path, LLM usage, and output format.**

The `scan_skill` tool lives in the NVIDIA/SkillSpector repository and serves as the primary bridge between MCP-compatible clients (such as Claude Code or Gemini CLI) and SkillSpector’s static analysis engine. When you start the MCP server using `skillspector mcp` or the `--mcp` extra, the tool registers itself with a FastMCP instance, making the full scanning pipeline available to remote agents without requiring direct shell access.

## How `scan_skill` Works Under the Hood

### MCP Server Architecture

In [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py), the `scan_skill` function is defined as an async Python function and wrapped by FastMCP as a callable tool. The server initialization follows this pattern:

1. Build a `FastMCP` server instance
2. Register `scan_skill` as an available tool
3. Listen on **stdio** (for local agents) or **HTTP** (for remote A2A callers)

When an MCP client invokes the tool, the server executes the same `run_scan` routine used by the native CLI, ensuring behavioral consistency across interfaces.

### Core Parameters and Return Types

The `scan_skill` signature accepts three primary arguments:

- **`target`** – Path or URL to the codebase to analyze
- **`use_llm`** – Boolean flag enabling LLM-based analyzers (e.g., for semantic vulnerability detection)
- **`output_format`** – String specifying the serialization format (`"json"`, `"sarif"`, etc.)

The tool returns marshalled findings directly to the MCP client, which then handles presentation or further processing.

## Running `scan_skill`: stdio vs HTTP Transports

### Local stdio Invocation

For local AI agents, start the server in stdio mode:

```bash

# Start the MCP server (exposes scan_skill on stdio)

skillspector mcp --transport stdio

```

Then invoke from Python using an MCP client:

```python
from mcp.client import FastMCPClient

client = FastMCPClient()  # connects to stdio server

result = client.run_tool(
    "scan_skill",
    {"target": ".", "use_llm": True, "output_format": "json"}
)
print(result)

```

### Remote HTTP Invocation

For distributed setups or remote agents, use HTTP transport:

```bash

# Start the server with HTTP transport on port 8080

skillspector mcp --transport http --port 8080

```

```python
import requests
import json

payload = {
    "target": "/path/to/skill",
    "use_llm": False,
    "output_format": "sarif"
}
resp = requests.post("http://localhost:8080/tools/scan_skill", json=payload)
print(json.dumps(resp.json(), indent=2))

```

## Security Model and Least-Privilege Design

The MCP implementation in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) includes specific guards against tool-poisoning attacks. When starting the server, you can pass `--no-mcp-config` to prevent loading external MCP server definitions, ensuring that `scan_skill` remains the only exposed tool. This limits the attack surface by preventing malicious third-party tool definitions from hijacking the MCP session.

Additionally, the scan pipeline invoked by `scan_skill` automatically runs MCP-specific analyses defined in the documentation files [`docs/B.3.1-mcp-least-privilege.md`](https://github.com/NVIDIA/SkillSpector/blob/main/docs/B.3.1-mcp-least-privilege.md) and [`docs/B.3.2-mcp-tool-poisoning.md`](https://github.com/NVIDIA/SkillSpector/blob/main/docs/B.3.2-mcp-tool-poisoning.md), checking for excessive permissions and unauthorized tool modifications.

## Programmatic Usage Without Network

You can also invoke `scan_skill` directly in Python without starting a network server, useful for testing or embedded workflows:

```python
from skillspector.mcp_server import build_server
import asyncio

# Build the FastMCP server programmatically

server = build_server()

async def run():
    findings = await server.tools["scan_skill"].call({
        "target": "./my_skill",
        "use_llm": True,
        "output_format": "json"
    })
    print(findings)

asyncio.run(run())

```

## Summary

- **`scan_skill`** is the singular MCP tool exposed by SkillSpector, defined in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) as an async function wrapped by FastMCP.
- It accepts **`target`**, **`use_llm`**, and **`output_format`** parameters, delegating execution to the internal `run_scan` routine.
- Transport options include **stdio** for local agents and **HTTP** for remote A2A callers, configurable via CLI flags in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py).
- The tool runs MCP-specific security checks including least-privilege validation and tool-poisoning detection.
- Start with `--no-mcp-config` to enforce a minimal attack surface by exposing only the `scan_skill` endpoint.

## Frequently Asked Questions

### What parameters does the `scan_skill` tool accept?

The tool requires a **`target`** path or URL specifying what to scan, accepts a boolean **`use_llm`** to toggle LLM-based analyzers, and expects an **`output_format`** string (such as `"json"` or `"sarif"`). These parameters map directly to the underlying `run_scan` configuration options used by the SkillSpector CLI.

### How does `scan_skill` differ from running SkillSpector directly?

While the CLI in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) offers interactive usage and file system access, `scan_skill` provides a sandboxed, programmatic interface accessible via the Model Context Protocol. It executes the identical analysis pipeline but returns structured data to MCP clients rather than writing to stdout or local files, making it suitable for agentic workflows.

### Is MCP support optional in SkillSpector?

Yes. MCP functionality is available as an optional extra. You only load the MCP server components and expose `scan_skill` when explicitly starting the server with `skillspector mcp` or the `--mcp` flag. Without these triggers, SkillSpector operates as a standard standalone CLI tool without opening MCP transport endpoints.

### What security checks run during a `scan_skill` invocation?

According to the source implementation, `scan_skill` triggers the full static-analysis graph including specialized MCP security analyzers. These include least-privilege checks (ensuring the scanned code doesn't request excessive permissions) and tool-poisoning detection (verifying that tool definitions haven't been maliciously altered), as documented in the repository's [`docs/B.3.1-mcp-least-privilege.md`](https://github.com/NVIDIA/SkillSpector/blob/main/docs/B.3.1-mcp-least-privilege.md) and [`docs/B.3.2-mcp-tool-poisoning.md`](https://github.com/NVIDIA/SkillSpector/blob/main/docs/B.3.2-mcp-tool-poisoning.md) files.