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

> Learn how to run and configure the MCP server for agent integration with NVIDIA SkillSpector. Expose the scan_skill tool for security scans via stdio or HTTP.

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

---

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

### Core Components

**`build_server()`** (lines 30-65 in [`src/skillspector/mcp_server.py`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/mcp_least_privilege.py) and [`mcp_tool_poisoning.py`](https://github.com/NVIDIA/SkillSpector/blob/main/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

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

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

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

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

```python
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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py)**: Main implementation containing `build_server()`, `run_scan()`, and `run()` functions
- **[`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py)**: Command-line interface exposing the `mcp` subcommand and transport options
- **[`src/skillspector/graph.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/graph.py)**: Analysis pipeline orchestration invoked by `run_scan()`
- **[`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/constants.py)**: Defines `RISK_THRESHOLD` used to calculate the `safe_to_install` flag
- **[`src/skillspector/models.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/models.py)**: Data models for findings and verdicts returned to agents
- **[`src/skillspector/mcp_least_privilege.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_least_privilege.py)**: Analyzer enforcing least-privilege constraints on MCP tools
- **[`src/skillspector/mcp_tool_poisoning.py`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py) with CLI entry points in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/mcp_server.py).