Connect MCP clients

Keep Aware hosts a Model Context Protocol (MCP) server that lets AI clients query your browser security data. Connect a client like Claude Desktop, Claude Code, Cursor, or any other OAuth-capable MCP client to give it access to a tenant you authorize.

The following tools are available today:

• search_events — Run Lucene queries against browser security events for a tenant.
• get_event_fields — Retrieve the event field schema, organized by category.
• query_metrics — Aggregate security metrics — counts, breakdowns, unique counts, sums, and time series — across events, assets, applications, extensions, instances, and policies.
• render_chart — Render a chart (donut, bar, stacked bar, line, or bar-over-time) inline in the conversation from data you already have. Clients that support MCP UI resources — Claude Desktop, claude.ai, and ChatGPT — show it as an interactive chart; other clients fall back to a text summary.

Getting started

Before anyone can connect a client, an admin must enable at least one MCP registration method in Capabilities under Allow MCP DCR or Allow MCP CIMD. Both default to off.

Console users need create_mcp_connections permission plus at least one of tools permissions in order to connect a client. The console user also needs an MCP client that supports OAuth 2.0 and the Streamable HTTP transport.

Enable MCP registration

MCP is opt-in per tenant. Until you enable a registration method, MCP authorization for the tenant fails. To enable MCP registration:

1. Navigate to Settings in the Keep Aware console.
2. Open the Capabilities tab.
3. Scroll to the MCP section.
4. Toggle on the registration method you want to allow:
   • Allow MCP clients via Dynamic Client Registration (DCR) — Clients register anonymously at connect time. Use this for most desktop and CLI clients, including Claude Desktop, Claude Code, and Cursor.
   • Allow MCP clients via Client ID Metadata Document (CIMD) — Clients are identified by a published metadata URL. Use this for clients that publish a metadata document, such as some browser-hosted or hosted-service MCP clients.

Both methods can be on at once

Enabling DCR and CIMD together is fine. Each MCP client uses whichever method it supports.

Grant user permissions

Assign the permissions that let users connect MCP clients and consent to MCP scopes.

1. Navigate to Console users in the Keep Aware console.
2. Under the actions for a user, click Edit user and select the permissions that should be allowed to connect MCP clients.
3. Enable the following permissions:
   • create_mcp_connections — Required to complete an MCP authorization flow.
   • mcp_events_search — Allows the user to consent to the mcp:events:search scope, which gates tools that search browser security events.
   • mcp_events_fields — Allows the user to consent to the mcp:events:fields scope, which gates tools that retrieve the event field schema.
   • mcp_metrics_query — Allows the user to consent to the mcp:metrics:query scope, which gates tools that aggregate security metrics and chart data.
   • mcp_charts_render — Allows the user to consent to the mcp:charts:render scope, which gates tools that render charts inline in the client.
4. Save the role.

A user only sees scopes whose paired permission they hold. For example, if a user has only mcp_events_fields, the consent screen only allows them to grant that single scope.

Connect a client

Once an admin has enabled registration and granted the right permissions, you can connect an MCP client to Keep Aware in two steps: add the Keep Aware MCP server URL to your client, then approve the consent screen.

The Keep Aware MCP server URL is:

https://cloud.awarefilter.com/mcp

Add the server to your MCP client

Claude Desktop

1. Open Settings → Connectors → Add custom MCP server.
2. Enter https://cloud.awarefilter.com/mcp as the server URL.
3. Save. Claude Desktop opens a browser tab to complete the OAuth consent step.

Claude Code

Run the following in your terminal:

claude mcp add keepaware https://cloud.awarefilter.com/mcp

Claude Code opens a browser tab to complete the OAuth consent step.

Cursor

1. Open Settings → MCP → Add server.
2. Enter https://cloud.awarefilter.com/mcp as the server URL.
3. Save. Cursor opens a browser tab to complete the OAuth consent step.

Other MCP clients

Any MCP client that supports OAuth 2.0 and the Streamable HTTP transport works with Keep Aware. Locate the client's "add MCP server" interface and enter https://cloud.awarefilter.com/mcp as the server URL. The client handles OAuth discovery automatically.

Approve the connection

After you add the server URL, your MCP client opens a browser tab on the Keep Aware console.

1. If you aren't already signed in, sign in with your Keep Aware account.
2. Select the tenant the client should access.
3. Review the requested scopes:
   • mcp:events:search — Search browser security events.
   • mcp:events:fields — View event field schema.
   • mcp:metrics:query — Query metrics and chart data.
   • mcp:charts:render — Render charts and visualizations.
4. Click Approve to grant access, or Deny to cancel.

After Approve, the browser hands control back to your MCP client, which receives an access token. The client can now call search_events, get_event_fields, query_metrics, and render_chart — limited to the scopes you approved — with results scoped to the tenant you selected.

Manage connections

• Navigate to Settings → Integrations → MCP to see the clients you have connected. Click Disconnect next to any client to revoke its access. Revocation is immediate.
• Console users with the appropriate permission can review and revoke MCP connections across all users in a tenant from the same area of the console.

Frequently asked questions

Question	Answer
What is the Keep Aware MCP server URL?	https://cloud.awarefilter.com/mcp. Add it to any OAuth-capable MCP client to start the connection flow.
What happens when I disconnect a client?	The client's access token is rejected on its next MCP request, typically within seconds. The user must reconnect the client to restore access.
Can one MCP connection access multiple tenants?	No. Each connection is scoped to a single tenant chosen at consent time. Connect the client a second time, and select a different tenant at the consent screen, to access another tenant.
Why does the consent screen say "this tenant has not enabled this type of MCP client registration"?	The tenant has not enabled the registration method (DCR or CIMD) the client is using. Ask an admin to enable the appropriate toggle in Capabilities.
Why don't I see any scopes to approve?	You may not hold the matching console permission for any MCP scope. Ask an admin to grant one or more of mcp_events_search, mcp_events_fields, mcp_metrics_query, or mcp_charts_render.
Why does a chart show up as text instead of a rendered chart?	render_chart returns an interactive chart only in clients that support MCP UI resources — Claude Desktop, claude.ai, and ChatGPT. Other clients receive an equivalent text summary of the same data.

Support

If a client isn't connecting, contact your Keep Aware Technical Representative with the client name, the tenant you're trying to authorize, and the display name shown for the connection.