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

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

# Start the MCP server (exposes scan_skill on stdio)

skillspector mcp --transport stdio

Then invoke from Python using an MCP client:

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:

# Start the server with HTTP transport on port 8080

skillspector mcp --transport http --port 8080

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

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 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.
• 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 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 and docs/B.3.2-mcp-tool-poisoning.md files.

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