Blackpoint Cyber API Patterns

Blackpoint Cyber (CompassOne) MCP Tools & API Patterns

Overview

Blackpoint Cyber is a managed detection and response (MDR) provider. The CompassOne portal exposes a partner-tenant-asset hierarchy: a partner (the MSP) sees many tenants (their customers), each tenant has many assets (endpoints, identities, cloud accounts), and detections / vulnerabilities are produced against those assets.

Connection & Authentication

Blackpoint uses an API token passed via header. CompassOne issues the token in the partner portal.

| Header | Value | |--------|-------| | X-Blackpoint-Api-Token | The raw CompassOne token |

The gateway maps the environment variable BLACKPOINT_API_TOKEN onto the X-Blackpoint-Api-Token header automatically. Internally, the Blackpoint MCP server forwards this to CompassOne as a Bearer token — you do not need to add the Bearer prefix yourself.

export BLACKPOINT_API_TOKEN="your-compassone-token"

Optional: BLACKPOINT_BASE_URL overrides the CompassOne base URL for regional or partner-specific deployments.

Hierarchy

Partner (MSP)
  └── Tenant (customer)
        └── Asset (endpoint / identity / cloud account)
              └── Detections / Vulnerabilities

Always pivot top-down: identify the tenant first, then drill into assets, then look at detections/vulnerabilities for that asset.

Navigation Tools

| Tool | Purpose | |------|---------| | blackpoint_navigate | Discover available domains | | blackpoint_back | Pop back to the prior context | | blackpoint_status | Health/status check |

Functional Tool Surface (today)

Tools follow blackpoint_<domain>_<action>. Currently functional domains:

• tenants
• assets
• detections
• vulnerabilities

Additional domains (alerts, cloud security, notifications, partners, threat intel, tickets) are stubbed in the MCP server but not yet implemented — do not call those.

Pagination

Blackpoint list endpoints use page/limit-style pagination. Always check whether more pages exist before claiming a result is complete, especially for detections and vulnerabilities — those can run into the thousands.

Error Handling

| Status | Meaning | Action | |--------|---------|--------| | 401 | Bad/missing Bearer token | Re-check BLACKPOINT_API_TOKEN | | 403 | Token valid but no access to the requested tenant | Check partner-tenant scoping | | 404 | Unknown tenant / asset / detection | Re-list to confirm | | 429 | Rate limit | Back off and retry |

Best Practices

• For incident-response work, always list the affected tenant's

assets and detections together — a detection without its asset context is hard to action.

• For multi-tenant rollups (partner view), iterate

blackpoint_tenants_list first and then drill in per-tenant.

• The current tool surface is read-only — there are no write tools

yet. Any "respond to detection" workflow must happen in the CompassOne portal itself.

Related Skills

• [incident-response](../incident-response/SKILL.md) - Primary investigation skill