MCP Tools

CortexVigil exposes its full toolset through a Model Context Protocol (MCP) server. MCP lets LLM clients (Claude Desktop, Cursor, VS Code Copilot, Claude.ai) call CortexVigil operations as tools.

Server URLs

• Staging: https://staging-api.cortexvigil.com/mcp
• Production: https://mcp.cortexvigil.com

The server speaks the MCP HTTP+SSE transport.

Authentication

Each MCP request authenticates with the same External App API key used for REST. Pass the key in the X-API-Key header. The key MUST have the mcp:invoke scope in addition to any per-resource scopes the called tool needs.

Example: a tool that lists cameras requires mcp:invoke AND read:cameras. A tool that enrols a face requires mcp:invoke AND write:faces.

Client Configuration

Claude Desktop / Claude.ai

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cortexvigil": {
      "url": "https://staging-api.cortexvigil.com/mcp",
      "headers": {
        "X-API-Key": "cvk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json with the same shape.

VS Code Copilot

Configure the MCP endpoint in the Copilot agent settings; supply the key as a custom header.

Tool Surface

The MCP server mirrors the REST coverage matrix documented in the repository at docs/architecture/MCP_AGENT_COVERAGE.md. Tools are namespaced by resource (e.g. cameras.list, events.query, faces.enroll).

A live list is available by calling the MCP tools/list method after connecting.

Per-App Authorisation Flow

1. The user installs the MCP client and pastes their cvk_* key.
2. Each tool call is sent as an MCP request with X-API-Key set.
3. The server resolves the key → app → site → scopes (cached for ~60 s).
4. If mcp:invoke AND the per-tool scope are present, the call is dispatched against the bound site.
5. Audit trail records (app_id, tool, site_id, args_hash, status) for every invocation.

Rate Limiting

MCP shares the same per-app rate_limit_per_min as REST. See Rate Limits.

Destructive Tools

A subset of tools (bulk delete, bulk export, biometric purge) are gated MCP-only and not exposed to the conversational agent surface. They still require explicit user confirmation in the MCP client.