Skip to content
English
  • There are no suggestions because the search field is empty.

Connect an MCP Client

Summary

CyberHQ.ai exposes an MCP (Model Context Protocol) server, so tools like Claude Desktop, Claude Code, or Cursor can query your platform data directly as part of a conversation, using the same API key and scopes as the REST API.

Before you start

The MCP tools are part of Iris, the built-in AI assistant, so they need the Ultimate plan. On Starter and Professional a key still connects, but your client sees an empty tool list rather than an error.

You'll need an API key, see Choose the right API key scopes for which scopes to grant. There are six tools, all read-only, and each needs one scope:

  • signals:read: search your signal inbox, list forward-looking risk forecasts, and list or open exposure chains (four tools).
  • users:read: look up a user.
  • assets:read: look up a vendor or AI platform.

Five of the six tools identify people (everything except the vendor lookup), so they appear only when your organization's Display mode is set to Named, under Configure → Organization → Data & privacy. With Pseudonymized (the default) or Aggregate only, your client sees just the vendor lookup, and only if the key holds assets:read.

Apart from that, an MCP client sees and can call the tools your key's scopes permit: there's no separate permission model to configure.

1. Point your MCP client at the endpoint

The MCP transport is a single endpoint: /api/public/v1/mcp. Configure your MCP-compatible client to connect there, authenticating with Authorization: Bearer <your key>. Bearer is the preferred method for MCP clients, and many clients either default to it or offer no way to set a custom header. The X-API-Key header used by the REST API is also accepted, for clients that do.

2. Know what you'll see

Your client's tool list reflects your plan, your key's scopes and your Display mode: a key without users:read simply won't show the user lookup tool. The tools are read-only: none of them change data in your organization. This is enforced on every call, not just when the tool list is built, so a scope can't be bypassed by calling a tool directly.

3. Use it like any other MCP server

Once connected, ask your client to use the available tools as part of a normal conversation: for example, searching recent signals or looking up a user or a vendor, scoped to whatever your key allows.

Confirm it worked

Your MCP client's tool list populates with tools matching your key's scopes (and your Display mode), and a call to one of them returns real data from your organization.

If it didn't work

  • The client can't connect (401): the key is missing, invalid, or no longer active because it was revoked, rotated, or passed its expiry date. Check the header and that you're sending the current key, as you would on the REST API.
  • It connects but no tools appear: MCP needs the Ultimate plan, so on Starter and Professional the tool list is empty. On Ultimate, check the key holds at least one of signals:read, users:read or assets:read, and check your Display mode.
  • Only the vendor lookup appears: your organization's Display mode isn't Named, so the tools that identify people are hidden. Calling one directly is refused with a message saying it needs the named display mode.
  • A 503 saying privacy settings are unavailable: the server couldn't read your organization's Display mode for that request. Retry after a moment; it's not a problem with your key.
  • Expected tools are missing: check your key's scopes; a tool tied to a scope you didn't grant simply won't appear. Scopes are fixed for the life of a key, so to add one, create a new key with the scopes you need and connect with that.

Related