vsa-x-mcp

MCP wrapper for VSA X API with centralized configuration and multiple endpoints for managing devices, assets, organizations, and rate limits.

Quick Start

1. Copy .env.sample to .env and configure:

   VSA_SERVER_NAME=your-vsa-server.example
   VSA_API_PATH=/api/v3
   PORT=3000
   READ_ONLY=true

2. Install dependencies:

   npm install

3. Start the server:

   npm start

Related MCP server: cisa-kev-mcp

Configuration

Environment Variables

Note: Use either VSA_SERVER_NAME + VSA_API_PATH (recommended) or VSA_BASE_URL (legacy).

Authentication

Clients authenticate using HTTP Basic Auth:

Authorization: Basic base64(TOKEN_ID:TOKEN_SECRET)

Example:

curl -u "your-token-id:your-token-secret" http://localhost:3000/devices

Endpoints

Health

• GET /health — Health check

Devices

• GET /devices — List all devices with optional pagination, filtering, and sorting

  • Query params: $top, $skip, $filter, $orderby, $count, scopeId

  • Example: GET /devices?$top=50&$skip=0&$filter=contains(tolower(Name),'server')

• GET /devices/:id — Get device details

• GET /devices/:id/assets — Get assets for a specific device

Organizations

• GET /organizations — List organizations with optional pagination, filtering, and sorting

  • Query params: $top, $skip, $filter, $orderby, $count

  • Example: GET /organizations?$top=20&$orderby=Name

Rate Limits

• GET /ratelimits — Get current rate limit status

Query Parameters

The list endpoints (/devices and /organizations) support OData query parameters for powerful filtering and pagination:

Devices Endpoint - Filterable Properties

Use these properties in $filter expressions: Identifier, Name, GroupId, GroupName, IsAgentInstalled, IsMdmEnrolled, SiteId, SiteName, OrganizationId, OrganizationName

Also supports: scopeId parameter for filtering by scope ID

Devices Endpoint - Sortable Properties

Use these properties in $orderby expressions: Identifier, Name, GroupId, GroupName, IsAgentInstalled, IsMdmEnrolled, SiteId, SiteName, OrganizationId, OrganizationName

Example requests:

# Get first 50 devices sorted by name
curl -u TOKEN_ID:TOKEN_SECRET "http://localhost:3000/devices?$top=50&$orderby=Name"

# Find devices with agent installed and in a specific organization
curl -u TOKEN_ID:TOKEN_SECRET "http://localhost:3000/devices?$filter=IsAgentInstalled eq true and OrganizationName eq 'Acme Corp'&$top=50"

# Paginate through devices with specific group, sorted by name
curl -u TOKEN_ID:TOKEN_SECRET "http://localhost:3000/devices?$top=100&$skip=100&$filter=GroupName eq 'Production'&$orderby=Name"

# Find devices in a specific scope that are not MDM enrolled
curl -u TOKEN_ID:TOKEN_SECRET "http://localhost:3000/devices?scopeId=123&$filter=IsMdmEnrolled eq false&$top=50&$orderby=Name desc"

# Filter organizations by name with total count
curl -u TOKEN_ID:TOKEN_SECRET "http://localhost:3000/organizations?$filter=startswith(Name,'Production')&$count=true"

Features

• ✅ Basic authentication forwarding per request

• ✅ Centralized API URL configuration

• ✅ Per-route write operation guards

• ✅ Error handling with upstream error details

• ✅ Rate limit headers forwarding

• ✅ OpenAPI documentation (openapi.yaml)

Write Operations

Write operations are guarded by READ_ONLY environment variable:

• When READ_ONLY=true (default), destructive operations are blocked

• To enable writes, set READ_ONLY=false or include confirm_destructive_action=true in the request

Testing

Run tests with:

npm test

API Documentation

See openapi.yaml for complete API specification and schema details.