blackpoint-mcp

Model Context Protocol (MCP) server for Blackpoint Cyber CompassOne - Managed Detection and Response (MDR) platform.

Features

This MCP server provides access to CompassOne's security capabilities through a decision-tree navigation interface:

Available Domains

• 🏢 Tenants: Customer tenant management

• 💻 Assets: Endpoint and server inventory (endpoint, server, network, cloud, mobile, iot)

• 🔍 Detections: Security detections and telemetry

• 🛡️ Vulnerabilities: Vulnerability management, dark web monitoring, external exposure scanning

Domain Structure

The server uses decision-tree navigation to organize tools:

1. Initial State: Navigation tools only (blackpoint_navigate, blackpoint_status)

2. Domain Entry: Navigate to a domain to see its specific tools

3. Domain Tools: Use domain-specific operations

4. Return: Use blackpoint_back to return to navigation

Tool Naming Convention

All tools follow the pattern: blackpoint_{domain}_{action}

Examples:

• blackpoint_assets_list - List assets by class

• blackpoint_detections_list - List security detections

• blackpoint_vulnerabilities_scans_list - List vulnerability scans

Installation

npm install blackpoint-mcp

Configuration

Environment Variables

Gateway Mode

When AUTH_MODE=gateway, the server reads credentials from HTTP headers:

• X-Blackpoint-API-Token → BLACKPOINT_API_TOKEN

This enables per-request authentication for multi-tenant gateways.

Usage

Standalone Mode (stdio)

# Set credentials
export BLACKPOINT_API_TOKEN="your-api-token"

# Run the server
blackpoint-mcp

Gateway Mode (HTTP)

export AUTH_MODE=gateway
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8080

blackpoint-mcp

Example Tool Calls

// Start by checking available domains
await tools.call("blackpoint_status");

// Navigate to assets domain
await tools.call("blackpoint_navigate", { domain: "assets" });

// List endpoint assets
await tools.call("blackpoint_assets_list", { 
  class: "endpoint",
  pageSize: 10 
});

// Get specific asset details
await tools.call("blackpoint_assets_get", { 
  id: "asset_12345" 
});

// Return to navigation
await tools.call("blackpoint_back");

API Coverage

✅ Implemented

📋 Planned

Partner vs Tenant Scoping

CompassOne uses hierarchical scoping: Partner → Tenants → Assets

• Partner tokens can access all associated tenants

• Tenant-scoped tokens are limited to specific customers

• Always specify tenantId parameters to avoid cross-tenant operations

Error Handling

The server provides structured error responses:

{
  "content": [{ 
    "type": "text", 
    "text": "Failed to list assets: Authentication failed" 
  }],
  "isError": true
}

Common error scenarios:

• Authentication: Invalid or expired API token

• Rate Limiting: Automatic retry with exponential backoff

• Not Found: Requested resource doesn't exist

• Validation: Invalid parameters or missing required fields

Rate Limiting

The underlying SDK implements automatic rate limiting:

• Default: 60 requests per minute (1 per second)

• 429 Handling: Honors Retry-After headers

• Backoff: Exponential backoff for subsequent requests

Docker

# Build
docker build -t blackpoint-mcp .

# Run in gateway mode
docker run -p 8080:8080 \
  -e AUTH_MODE=gateway \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_PORT=8080 \
  blackpoint-mcp

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test
npm test

# Lint
npm run lint

Security Considerations

API Access Requirements

• CompassOne Partner Agreement required for API access

• Partner-tier credentials needed for multi-tenant operations

• Scoped tokens recommended for tenant-specific access

Destructive Operations

The following operations require confirmation (when implemented):

• Asset isolation/response actions

• Ticket status changes with actions

• Alert acknowledgment/closure

• Remediation workflows

These use the elicitConfirmation pattern to prevent accidental execution.

Troubleshooting

Common Issues

No tools showing:

• Check BLACKPOINT_API_TOKEN is set

• Verify token has correct scopes

• Check network connectivity to CompassOne API

Gateway mode not working:

• Verify AUTH_MODE=gateway is set

• Check HTTP headers are passed correctly

• Confirm container networking allows connections

Rate limiting:

• Monitor logs for 429 responses

• Consider reducing request frequency

• Verify token isn't shared across instances

Debug Logging

export LOG_LEVEL=debug
blackpoint-mcp

Health Check

# Test basic connectivity
curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -H "X-Blackpoint-API-Token: your-token" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Make your changes and add tests

4. Follow the domain handler pattern for new capabilities

5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

Apache-2.0 - see LICENSE for details.