{
  "markdown": "# blackpoint-mcp\n\nModel Context Protocol (MCP) server for Blackpoint Cyber CompassOne - Managed Detection and Response (MDR) platform.\n\n## Features\n\nThis MCP server provides access to CompassOne's security capabilities through a decision-tree navigation interface:\n\n### Available Domains\n\n- **🏢 Tenants**: Customer tenant management\n- **💻 Assets**: Endpoint and server inventory (endpoint, server, network, cloud, mobile, iot)  \n- **🔍 Detections**: Security detections and telemetry\n- **🛡️ Vulnerabilities**: Vulnerability management, dark web monitoring, external exposure scanning\n\n### Domain Structure\n\nAll implemented tools are listed together in a single `tools/list` call — no\nnavigation step required. `blackpoint_status` reports current health and\navailable domains, and `blackpoint_navigate`/`blackpoint_back` remain for\nclients that like a guided menu, but they're optional: every domain tool\n(`blackpoint_tenants_*`, `blackpoint_assets_*`, `blackpoint_detections_*`,\n`blackpoint_vulnerabilities_*`) is callable directly from the start.\n\n(Earlier versions gated domain tools behind a `blackpoint_navigate` call.\nThat doesn't work behind the Conduit gateway — Conduit suppresses\n`_navigate`/`_back` from every vendor's tool list for security reasons, which\nmade every domain tool unreachable through it. The list is flat now so it\nworks the same everywhere.)\n\n### Tool Naming Convention\n\nAll tools follow the pattern: `blackpoint_{domain}_{action}`\n\nExamples:\n- `blackpoint_assets_list` - List assets by class\n- `blackpoint_detections_list` - List security detections\n- `blackpoint_vulnerabilities_scans_list` - List vulnerability scans\n\n## Installation\n\n```bash\nnpm install blackpoint-mcp\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `BLACKPOINT_API_TOKEN` | CompassOne API token | Yes |\n| `BLACKPOINT_BASE_URL` | API base URL (may vary by region/partner) | No |\n| `MCP_TRANSPORT` | Transport mode: `stdio` or `http` | No (default: stdio) |\n| `MCP_HTTP_PORT` | HTTP port for gateway mode | No (default: 8080) |\n| `AUTH_MODE` | Set to `gateway` for header-based auth | No |\n| `LOG_LEVEL` | Logging level: debug, info, warn, error | No (default: info) |\n\n### Gateway Mode\n\nWhen `AUTH_MODE=gateway`, the server reads credentials from HTTP headers:\n\n- `X-Blackpoint-API-Token` → `BLACKPOINT_API_TOKEN`\n\nThis enables per-request authentication for multi-tenant gateways.\n\n## Usage\n\n### Standalone Mode (stdio)\n\n```bash\n# Set credentials\nexport BLACKPOINT_API_TOKEN=\"your-api-token\"\n\n# Run the server\nblackpoint-mcp\n```\n\n### Gateway Mode (HTTP)\n\n```bash\nexport AUTH_MODE=gateway\nexport MCP_TRANSPORT=http\nexport MCP_HTTP_PORT=8080\n\nblackpoint-mcp\n```\n\n### Example Tool Calls\n\n```typescript\n// Start by checking available domains\nawait tools.call(\"blackpoint_status\");\n\n// Navigate to assets domain\nawait tools.call(\"blackpoint_navigate\", { domain: \"assets\" });\n\n// List endpoint assets\nawait tools.call(\"blackpoint_assets_list\", { \n  class: \"endpoint\",\n  pageSize: 10 \n});\n\n// Get specific asset details\nawait tools.call(\"blackpoint_assets_get\", { \n  id: \"asset_12345\" \n});\n\n// Return to navigation\nawait tools.call(\"blackpoint_back\");\n```\n\n## API Coverage\n\n### ✅ Implemented\n\n| Domain | Tools | Description |\n|--------|-------|-------------|\n| **tenants** | `list`, `get` | Customer tenant management |\n| **assets** | `list`, `get`, `relationships`, `search` | Asset inventory and relationships |\n| **detections** | `list`, `get` | Security detections and telemetry |\n| **vulnerabilities** | `list`, `scans_list`, `darkweb_list`, `external_list` | Vuln management, dark web, external exposure |\n\n### 📋 Planned\n\n| Domain | Status | Notes |\n|--------|--------|--------|\n| **partners** | SDK ready | Account management - ready to implement |\n| **alerts** | Models only | API handlers not available in CompassOne wrapper |\n| **tickets** | Models only | API handlers not available in CompassOne wrapper |\n| **cloud_security** | SDK ready | M365/Google/Cisco onboarding - ready to implement |\n| **notifications** | SDK ready | Contact groups and channels - ready to implement |\n\n## Partner vs Tenant Scoping\n\nCompassOne uses hierarchical scoping: **Partner → Tenants → Assets**\n\n- **Partner tokens** can access all associated tenants\n- **Tenant-scoped tokens** are limited to specific customers\n- Always specify `tenantId` parameters to avoid cross-tenant operations\n\n## Error Handling\n\nThe server provides structured error responses:\n\n```json\n{\n  \"content\": [{ \n    \"type\": \"text\", \n    \"text\": \"Failed to list assets: Authentication failed\" \n  }],\n  \"isError\": true\n}\n```\n\nCommon error scenarios:\n- **Authentication**: Invalid or expired API token\n- **Rate Limiting**: Automatic retry with exponential backoff\n- **Not Found**: Requested resource doesn't exist\n- **Validation**: Invalid parameters or missing required fields\n\n## Rate Limiting\n\nThe underlying SDK implements automatic rate limiting:\n\n- **Default**: 60 requests per minute (1 per second)\n- **429 Handling**: Honors `Retry-After` headers\n- **Backoff**: Exponential backoff for subsequent requests\n\n## Docker\n\n```bash\n# Build\ndocker build -t blackpoint-mcp .\n\n# Run in gateway mode\ndocker run -p 8080:8080 \\\n  -e AUTH_MODE=gateway \\\n  -e MCP_TRANSPORT=http \\\n  -e MCP_HTTP_PORT=8080 \\\n  blackpoint-mcp\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode\nnpm run dev\n\n# Build\nnpm run build\n\n# Test\nnpm test\n\n# Lint\nnpm run lint\n```\n\n## Security Considerations\n\n### API Access Requirements\n\n- **CompassOne Partner Agreement** required for API access\n- **Partner-tier credentials** needed for multi-tenant operations\n- **Scoped tokens** recommended for tenant-specific access\n\n### Destructive Operations\n\nThe following operations require confirmation (when implemented):\n\n- Asset isolation/response actions\n- Ticket status changes with actions\n- Alert acknowledgment/closure\n- Remediation workflows\n\nThese use the `elicitConfirmation` pattern to prevent accidental execution.\n\n## Troubleshooting\n\n### Common Issues\n\n**No tools showing**:\n- Check `BLACKPOINT_API_TOKEN` is set\n- Verify token has correct scopes\n- Check network connectivity to CompassOne API\n\n**Gateway mode not working**:\n- Verify `AUTH_MODE=gateway` is set\n- Check HTTP headers are passed correctly\n- Confirm container networking allows connections\n\n**Rate limiting**:\n- Monitor logs for 429 responses\n- Consider reducing request frequency\n- Verify token isn't shared across instances\n\n### Debug Logging\n\n```bash\nexport LOG_LEVEL=debug\nblackpoint-mcp\n```\n\n### Health Check\n\n```bash\n# Test basic connectivity\ncurl -X POST http://localhost:8080/ \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Blackpoint-API-Token: your-token\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}'\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Follow the domain handler pattern for new capabilities\n5. Submit a pull request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## License\n\nApache-2.0 - see [LICENSE](LICENSE) for details.",
  "bytes": 7191,
  "sha": "ce80bd74430f5dc99f0790c4b0ff7bb434cb42e525cb5472414234c0b6741ec5",
  "repo_slug": "wyre-technology/blackpoint-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wyre_technology_blackpoint_mcp_cb67f623/readme"
}