CortexVigil API Reference

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

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

Important: Most MCP clients (Claude Desktop, Claude.ai web "Connectors", Cursor connector dialog, ChatGPT) do not yet expose a UI field for custom headers like X-API-Key. The community-standard mcp-remote stdio bridge wraps our remote HTTP MCP server as a local stdio server and injects the header for you. It works with every MCP client today.

Claude Desktop (recommended — mcp-remote bridge)

Requires Node.js 18+ installed locally. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cortexvigil": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.cortexvigil.com/mcp",
        "--header",
        "X-API-Key:cvk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Restart Claude Desktop. The cortexvigil tools will appear in the tool picker.

Locations of claude_desktop_config.json:

Cursor

Add to ~/.cursor/mcp.json with the same command + args shape as above. Cursor uses the identical MCP config schema as Claude Desktop.

VS Code Copilot (GitHub Copilot Chat)

VS Code Copilot's MCP http transport supports headers natively — no bridge needed. Add to your VS Code settings.json (User or Workspace):

{
  "settings": {
    "mcp": {
      "servers": {
        "CortexVigil": {
          "url": "https://mcp.cortexvigil.com/mcp",
          "type": "http",
          "headers": {
            "X-API-Key": "cvk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          }
        }
      },
      "inputs": []
    }
  }
}

Reload the VS Code window. The CortexVigil tools become available in Copilot Chat's agent mode tool picker.

Claude.ai web ("Custom Connector") and ChatGPT

The web "Custom Connector" dialog currently supports OAuth2 only — there is no header field for API keys. OAuth2 support is on the CortexVigil roadmap (v2). Until then, please use Claude Desktop with the mcp-remote bridge above.

Native HTTP+SSE (advanced — own MCP client)

If you are building your own MCP client (or using a client that supports custom headers directly), connect natively:

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.