How to Run and Configure the MCP Server for Agent Integration with SkillSpector

SkillSpector provides a lightweight MCP (Model Context Protocol) server that exposes the scan_skill tool, enabling agents to invoke security scans via stdio or HTTP transport before installing skills.

NVIDIA's SkillSpector repository includes a built-in MCP server that transforms its static-analysis engine into an agent-callable security tool. This integration allows AI agents and CLI tools to programmatically validate skills through the Model Context Protocol, receiving structured risk verdicts with honest LLM accounting.

Architecture of the SkillSpector MCP Server

The MCP server implementation follows a modular design that separates server construction, scan execution, and transport handling across distinct functions in src/skillspector/mcp_server.py.

Core Components

build_server() (lines 30-65 in src/skillspector/mcp_server.py) constructs a FastMCP server instance using the optional mcp SDK and registers the scan_skill tool.

run_scan() (lines 47-75) executes the SkillSpector analysis graph on the supplied target. It accepts Git URLs, zip archives, markdown files, or local directories, returning a structured JSON verdict containing risk scores, severity ratings, recommendations, findings, and LLM usage metadata.

run() (lines 68-79) serves as the entry point that initializes the server with the chosen transport (stdio or HTTP) and begins listening for tool invocations.

CLI integration in src/skillspector/cli.py exposes the skillspector mcp command, parsing arguments for transport selection, host/port configuration, and output formatting.

Credential resolution occurs via resolve_provider_credentials() (lines 75-77). When valid API keys are found for the configured LLM provider, the scan includes a semantic analysis pass; otherwise, it falls back to static-only analysis and sets the llm_used flag accordingly.

Execution Flow

1. The CLI invokes run() with transport parameters.
2. run() instantiates a FastMCP server through build_server().
3. The server registers the scan_skill tool that forwards requests to run_scan().
4. run_scan() builds an analysis graph via skillspector.graph, executing static analyzers (including MCP-specific modules like mcp_least_privilege.py and mcp_tool_poisoning.py) plus an optional LLM pass.
5. Results are processed through cleanup_result and returned as JSON containing risk_score, safe_to_install status, and honest LLM accounting fields.

Running the MCP Server for SkillSpector

Before starting the server, install the optional MCP dependencies to enable FastMCP support.

Prerequisites

pip install "skillspector[mcp]"

stdio Transport for Local Agents

Use stdio transport when integrating with locally-run agents like Claude Code or Codex CLI that communicate over standard input/output streams:

skillspector mcp

The server remains active in the terminal, listening for tool invocations from MCP-compatible clients on the same machine.

HTTP Transport for Remote Integration

For remote agents, containerized environments, or A2A (Agent-to-Agent) scenarios, use HTTP transport with explicit host and port binding:

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

This configuration exposes the scan_skill tool over the streamable-HTTP protocol, allowing cross-network agent integration.

Configuring Output Formats

The scan_skill tool supports multiple report formats via the --output-format flag:

• json (default): Structured data for programmatic consumption
• markdown: Human-readable reports
• sarif: Static Analysis Results Interchange Format for CI/CD integration
• terminal: Console-formatted output

Example:

skillspector mcp --output-format markdown

Configuring MCP Server Scan Parameters

When invoking scan_skill directly from agent code or CLI arguments, the following parameters control scan behavior:

Parameter	Type	Description	Default
target	string	Path or URL to scan (Git repo, zip, markdown, or directory)	Required
use_llm	boolean	Request LLM semantic analysis (only executes if credentials resolve)	True
output_format	string	Report format: json, markdown, sarif, or terminal	json
yara_rules_dir	string	Directory containing custom YARA signatures	None

Direct Tool Invocation Example

result = await mcp_client.scan_skill(
    target="https://github.com/example/my-skill.git",
    use_llm=False,
    output_format="json"
)

print(f"Risk Score: {result['risk_score']}")
print(f"Safe to Install: {result['safe_to_install']}")
print(f"LLM Used: {result['llm_used']}")

The response always includes honest LLM accounting fields:

• llm_requested: Whether the client asked for LLM analysis
• llm_available: Whether credentials were found
• llm_used: Whether the LLM actually ran
• scan_mode: The execution mode (static-only or augmented)

Key Implementation Files

The MCP server functionality spans several modules in the SkillSpector codebase:

• src/skillspector/mcp_server.py: Main implementation containing build_server(), run_scan(), and run() functions
• src/skillspector/cli.py: Command-line interface exposing the mcp subcommand and transport options
• src/skillspector/graph.py: Analysis pipeline orchestration invoked by run_scan()
• src/skillspector/constants.py: Defines RISK_THRESHOLD used to calculate the safe_to_install flag
• src/skillspector/models.py: Data models for findings and verdicts returned to agents
• src/skillspector/mcp_least_privilege.py: Analyzer enforcing least-privilege constraints on MCP tools
• src/skillspector/mcp_tool_poisoning.py: Detector for malicious tool definitions and poisoning attacks

Summary

• Install the MCP server with pip install "skillspector[mcp]" to enable FastMCP dependencies
• Start the server using skillspector mcp for stdio transport or skillspector mcp --transport http --host 0.0.0.0 --port 8000 for HTTP
• Agents invoke the scan_skill tool with a target URL/path and optional use_llm parameter
• The server returns JSON verdicts containing risk scores, safe_to_install boolean, and transparent LLM accounting fields
• Implementation resides in src/skillspector/mcp_server.py with CLI entry points in src/skillspector/cli.py

Frequently Asked Questions

What transports does the SkillSpector MCP server support?

The server supports stdio (default) for local CLI agents and HTTP for remote or containerized deployments. Specify the transport using --transport http along with --host and --port parameters. The stdio transport is ideal for Claude Code and similar local agents, while HTTP enables A2A (Agent-to-Agent) communication across networks.

How does the server handle missing LLM credentials?

When use_llm=True but resolve_provider_credentials() cannot find valid API keys in src/skillspector/mcp_server.py lines 75-77, the scan automatically falls back to static analysis only. The response includes llm_requested: true, llm_available: false, and llm_used: false, ensuring transparent accounting of why the semantic pass was skipped.

Can I use custom YARA rules with the MCP server?

Yes. Pass the yara_rules_dir parameter when calling scan_skill to specify a directory containing additional YARA signatures. The server loads these rules alongside the built-in static analyzers during the run_scan() execution, allowing customized detection patterns for specific organizational security requirements.

What is the difference between llm_requested and llm_used in the response?

llm_requested indicates the client asked for LLM analysis, while llm_used confirms the LLM actually executed. If credentials are missing or the provider is unavailable, llm_used will be false despite the request. This distinction enables agents to understand whether they received a full semantic analysis or a static-only verdict based on the conditions documented in src/skillspector/mcp_server.py.

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