MCP Server

ShieldedStack exposes a read-only Model Context Protocol (MCP) server so AI coding agents and security assistants can answer dependency and vulnerability questions using data from your ShieldedStack workspace.

The MCP server is hosted by the ShieldedStack Portal at /mcp and uses Streamable HTTP. The same Portal service serves the browser UI and API; MCP is not served by the package proxy.

Server URL

MCP is served by the Portal at:

<portal-url>/mcp

MCP uses Streamable HTTP. The endpoint accepts MCP requests rather than serving a web page, so opening it in a browser sends a GET request and returns 404 Not Found by design.

What You Can Ask

Use MCP when you want an agent to answer questions like:

• Which projects use lodash?
• Show me high or critical CVEs in this workspace.
• Which packages should we prioritize by risk score?
• Which packages are deprecated or far behind latest?
• Give me the package inventory for the npm ecosystem.

The server is read-only. It does not edit repositories, mutate ShieldedStack policy, acknowledge alerts, or change package-manager configuration.

Authentication

MCP uses ShieldedStack API keys created in Settings -> API Keys with Allow read-only workspace data access enabled. Keys without this capability remain valid for package proxy authentication but cannot access MCP.

MCP accepts only bearer authentication:

Authorization: Bearer YOUR_API_KEY_HERE

Scope

An API key with workspace-read access grants read access to the key’s workspace.

The API key’s project name is still useful for audit and organization, but it does not restrict MCP results to that project. If you want project-specific answers, ask for a project filter in your prompt or provide the project tool argument.

Available Tools

Tool	Use case
find_vulnerabilities	Search CVEs and advisories by ecosystem, project, severity, or text.
find_risky_packages	Find packages ranked by risk score, advisory count, and CVSS.
find_outdated_packages	Find deprecated or stale packages compared with latest release dates.
get_project_inventory	Find package usage across projects in the workspace.

Tool Arguments

Common optional arguments include:

• ecosystem: npm, nuget, pip, maven, go, cargo, rubygems, or dart.
• project: Project name filter. Omit it to search the whole workspace.
• search: Package, advisory, or text search depending on the tool.
• skip and take: Pagination controls.
• sortBy and sortOrder: Report-specific sorting.

find_vulnerabilities also accepts severityAtLeast, for example high or critical.

find_outdated_packages also accepts daysOlderThanNewestPublishDate, which defaults to 180 days.

VS Code Configuration

Create or update .vscode/mcp.json in your repository or workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "shieldedstack_api_key",
      "description": "ShieldedStack API key",
      "password": true
    }
  ],
  "servers": {
    "shieldedstack": {
      "type": "http",
      "url": "<portal-url>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:shieldedstack_api_key}"
      }
    }
  }
}

Example Prompts

After your MCP client is connected, try prompts like:

Which projects use left-pad in this ShieldedStack workspace?

Show me high and critical vulnerabilities for npm packages.

Find risky packages in the Backend project and summarize why they are risky.

Which NuGet packages are outdated by more than 365 days?

API Key Hygiene

• Create dedicated API keys with workspace-read access for MCP clients so you can rotate and revoke them independently.
• Leave workspace-read access disabled for package proxy clients.
• Store MCP keys in your editor’s secret input, local secret store, or CI secret manager.
• Do not commit .vscode/mcp.json if it contains a literal API key. Prefer ${input:...} placeholders.
• Revoke MCP keys immediately if they are exposed.

Troubleshooting

MCP client says unauthorized

Check that the header is exactly Authorization: Bearer <api-key>, the key has workspace-read access enabled, and it has not been revoked or expired.

Tools are not listed

Verify the URL ends with /mcp and points at the Portal service, not the package proxy.

Opening the MCP URL returns 404

This is expected in a browser because it sends a GET request. Configure the URL in a Streamable HTTP MCP client, which sends MCP messages to the endpoint with POST.

Browser-based client receives CORS errors

The client origin has to be included in the Portal CORS configuration.

Results include more than one project

That is expected. MCP keys are workspace-scoped. Ask for a specific project or pass the project argument when you need narrower results.

The client connects but does not call tools

Some agents answer from model knowledge unless you explicitly reference the tool or ShieldedStack data. Try prompts such as Use ShieldedStack MCP to find... or select the ShieldedStack tools in your MCP client UI.