MCP access

Perpetual exposes most of its capabilities through Model Context Protocol (MCP) at /mcp. External agents connect to this endpoint to work with Perpetual.

For the opposite direction, where Perpetual calls the tools of a remote server you have configured as content, see MCP Servers.

MCP access is one of Perpetual's three surfaces, alongside the web app and the API. It reaches the same resources the other two do. A client authorizes with an OAuth access token, then calls tools over JSON-RPC. Those tools reach Hamelin queries, content, cases, and the changesets that content is staged in. Every call acts as the user the token belongs to, inside the single organization the token names. Perpetual resolves that user's roles at the moment of the call.

Endpoint

Perpetual serves MCP at /mcp on the same host as the web app, using the Streamable HTTP transport.

Perpetual periodically closes the server-to-client event stream. Clients must reconnect when the stream closes.

Authorization

/mcp accepts an OAuth access token and nothing else. OAuth covers registering a client, the grants, the discovery documents, and what a token carries.

Requests require an OAuth bearer token identifying a user and exactly one organization. Browser sessions and data-plane tokens cannot authorize MCP calls.

Both the client_credentials and authorization_code grants produce OAuth tokens for MCP access. MCP clients that use the standard authorization flow redirect you to Perpetual to sign in and approve access, then obtain a token through the authorization_code grant.

Scope

The access token identifies the organization. Where relevant, a tool's arguments identify the resource it acts on, including:

• A resource ID (such as resourceId, caseId, or dashboardId).
• A Space ID (spaceId).
• A content pack ID (contentPackId).

Each tool's Inputs table documents the identifiers it accepts.

Tools

Harnesses discover the available Perpetual tools when they connect. The groups below describe what those tools can do.

Tools can change

Perpetual may add, rename, or change tools. Reconnect your MCP client to discover the current tool set.

The MCP server registers 103 tools, in seven groups.

Group	Tools
Deployable content tools	create-detection, update-detection, delete-detection, list-detections, validate-detection-deployment, create-integration, update-integration, delete-integration, list-integrations, create-integration-parser, update-integration-parser, delete-integration-parser, create-integration-mapper, update-integration-mapper, delete-integration-mapper, create-lookup, update-lookup, delete-lookup
Dataset resource tools	create-table, update-table, delete-table, create-view, update-view, delete-view, create-union, update-union, delete-union, create-connector, update-connector, delete-connector, list-connector-names
Other content tools	create-dashboard, update-dashboard, update-dashboard-panels, update-dashboard-variables, create-http-tool-config, update-http-tool-config, delete-http-tool-config, preview-http-tool-config, test-http-tool-config, create-mcp-config, update-mcp-config, delete-mcp-config, probe-mcp-server, rediscover-mcp-tools, delete-dashboard, create-webhook, update-webhook, delete-webhook, preview-webhook-config, create-skill, update-skill, delete-skill
Query and schema tools	execute-hamelin-query, validate-hamelin-query, get-query-performance, list-dataset-names, get-dataset-columns, get-ecs-schema, get-signal-schema, get-hamelin-language-guide, search-hamelin-documentation, search-perpetual-documentation, get-resource-engineering-guide
Changeset tools	create-changeset, update-changeset, delete-changeset, get-changeset, list-changesets, validate-changeset, discard-changeset-change, propose-changeset, commit-changeset
Case and alert tools	get-alert, list-alerts, promote-alert, create-case, list-cases, get-case-info, update-case-info, get-case-blocks, get-case-audit-logs, add-comment, add-analysis-block, add-log-block, add-note-block, add-task-block
Resource and Space tools	create-folder, update-folder, delete-folder, get-content-work-item, get-resource, search-resources, list-spaces, create-content-pack, update-content-pack, delete-content-pack, list-content-packs, add-to-content-pack, install-content-pack, list-content-pack-installations, update-content-pack-installation, uninstall-content-pack-installation

Three of the Simba agent's tools are absent here: execute-code, skill, virus-total-lookup-indicator.

commit-changeset publishes staged changes. An agent can stage content, validate it, propose it for review, and commit it. Existing access checks and commit validation still apply.

Related

• OAuth, the authorization server a client registers with and the token it presents.
• MCP Servers, the content resource that points the other way.
• The Simba agent, which reaches the same tools from inside Perpetual.
• User and Roles, the identity a call acts as and what decides its access.
• Changesets, where a content write over MCP lands.
• Resource, the model all three surfaces reach.