Connect an MCP client

Open Manage → AI & MCP → Your MCP connections. This panel shows the endpoint, client configuration examples, tool catalog and your personal tokens. External clients use their own model; the account’s Assistant model setting configures the in-product Spear Assistant.

Create a connection

1. Choose New token and enter a recognizable client name.
2. Choose a scope and expiry. Use read for investigation; write permits supported mutations as well.
3. Copy the token when shown. Its secret is stored hashed and cannot be retrieved later.
4. Copy the endpoint and configuration snippet for your client from this page. Replace the token placeholder with the secret, then connect from the client.

The endpoint is /v1/portal/mcp on your deployment. Use the displayed full URL so the hostname and any deployment routing match. Authentication uses an Authorization: Bearer header. Keep the token out of source control and shared documents.

Creating tokens requires ai:manage. With ai:read, you can inspect the panel and revoke your own tokens. Other users manage their own tokens; this is not an administrator’s view of everyone’s credentials.

Understand the scope

List tools return bounded overview pages. Inspect items, total, and next_offset; continue a collection with its response_path and response_offset. Keep the same filters and endpoint page/cursor arguments. The endpoint’s next_cursor advances to another underlying page.

Use a matching detail tool for deeper investigation. For example, list_incidents gives incident summaries, get_incident retrieves breach evidence, and get_incident_logs retrieves attached log captures. Log access requires both incident:read and agent:manage. Pending, skipped or expired captures mean the evidence is unavailable; they do not mean no errors occurred. Detail and log tools expose response_path, offset, and limit to inspect large fields without truncating the response. For lists without a detail tool, select the original record or field with response_path.

A token acts as its creator in the organization, capped by its scope and the creator’s current permissions. A write token does not grant administrator access. Writes additionally require ai:execute and permission to manage the affected resource. Losing access to that resource also affects subsequent tool calls.

The catalog identifies read, write and destructive tools. Clients can inspect tests, agents, incidents, metrics and other supported resources. Usage tools require billing:view; usage policy changes require billing:manage as well as AI write access. Cost estimates are not invoices and these tools do not make payments.

External MCP writes follow the client’s interaction model and token permissions. They do not open Spear Assistant’s in-product approval card. Review your client’s tool approval settings before enabling write access.

Skills in external clients

OpenTelemetry tools cover source inspection, Collector configuration templates, source name/signal/expiry edits and revocation, service discovery, and span/log/profile search and detail. Reads keep the caller’s account, permissions and fixed time window. Use get_query_language_spec(topic="opentelemetry") for imported metric discovery and MetricQL examples, or the skill/otel workflow. Ingestion tokens are separate from MCP tokens and are created in the secure OpenTelemetry setup page; token values never belong in assistant arguments or results. See OpenTelemetry setup.

MCP exposes workflows through prompts/list and prompts/get, using names such as skill/investigate. Prompts include instructions and declared tool guidance; the client controls its own tool loading. The portal’s question form is not MCP elicitation: answer follow-up questions through your client’s interface or chat.

Rotate, revoke and troubleshoot

To rotate a token, create a replacement, update the client, then revoke the old token. Revocation takes effect on its next call. If a secret is lost, create a new token rather than trying to recover it.

• If connection fails, check the displayed endpoint, bearer header, expiry and revocation status.
• If reads work but writes fail, check scope, ai:execute and the resource permission.
• If data is empty, verify the organization, target, placement and time window in the portal.

See Users & roles for permission management.