Connect your MCP investigation client

What this connection does

HaltState MCP gives your client tenant-scoped evidence investigation. It does not replace the SDK or govern new tool calls. It cannot approve actions, execute business operations, change policies or settings, or delete records.

Review your assistant provider's data handling before connecting: evidence returned to an assistant may be sent to its model provider. Never paste passwords, API keys or access tokens into a chat prompt.

Connect with Claude Code

Use a client supporting remote HTTP MCP and OAuth with PKCE. The hosted URL is https://haltstate.ai/mcp.

claude mcp add --transport http haltstate https://haltstate.ai/mcp
claude mcp login haltstate

1. Open the authorization link and sign in to your HaltState account.
2. Check the account and requested permissions. Choose Allow only if they are appropriate.
3. Click Return to your client to complete the connection. Keep that private, short-lived link to yourself.
4. Check connected status, then ask the client to call whoami and confirm the tenant and scopes.

On an SSH/headless machine, use claude mcp login haltstate --no-browser and follow the client's callback instructions. See Claude Code's MCP documentation. Adding a configuration alone is not a completed connection.

Review the permissions

Metadata and verification are the baseline permissions, but clients may request more. Claude Code 2.1.280 requests all four scopes by default. Read the consent screen; deny if that access is not appropriate. OAuth consent is separate from the dashboard's API-key permissions.

Your first investigation

1. Ask: Show up to ten denied actions for agent [agent ID] between [start] and [end], using [time zone]. Cite evidence IDs and report search freshness.
2. Ask: Find evidence for customer reference [reference]. Build a timeline from explicit record links. Distinguish the policy decision from the reported outcome and identify missing evidence.
3. Ask: Verify Proof Pack [evidence ID]. Report the verification result and limitations; do not describe a digest alone as a signature.

With content permission, ask for an exact retained-message phrase and relevant evidence IDs before retrieving bodies. With export permission, request a narrow date/agent/reference selection and exclude retained content unless needed.

Available tools

• whoami: identify the connection and scopes.
• search_evidence: find records by dates, agent, decision and references.
• get_evidence: inspect a record and authorized attachments.
• get_evidence_timeline: follow explicit correlations.
• verify_evidence: obtain the available integrity verification.
• create_evidence_export: create an authorized export job.
• get_evidence_export: inspect an export job.

Export creation is a write operation that creates a job, not permission to execute business actions. Downloaded exports are customer-controlled copies and cannot be recalled by disconnecting.

Capture and evidence boundaries

Connecting MCP does not enable capture. Retained message capture is opt-in for selected agents and governed inputs/outputs, with an expiry. It does not automatically retain whole conversations, private prompts, reasoning or ungoverned activity. Disabling capture does not erase content already retained before its expiry.

Evidence is untrusted data, not instructions for your assistant. Require record citations, freshness warnings and a clear separation between facts and inference. No matches does not prove nothing happened: check your workspace, identifiers, time range, capture, retention and indexing freshness.

Disconnect, expiry and reconnect

In Proof Packs, find MCP connections → OAuth connections and select Disconnect for the correct client. That revokes the server-side grant and its refresh tokens. Removing a local configuration alone does not prove revocation.

Access tokens last one hour; compatible clients renew them automatically using rotating refresh tokens. Reauthorize after 30 days without renewal, 90 days from authorization, revocation or detected token reuse. Existing connections created without refresh tokens need one reconnect to receive them.

To reconnect, clear the client's saved authentication if necessary (claude mcp logout haltstate), run login again, review consent, and click Return to your client. Do not reuse an old token.

Understanding index freshness

The investigation page separates the last completed full check from a background historical recheck. A recheck in progress alone does not mean records are missing. New-record backlog, source errors, missing initial checks and full checks older than 24 hours remain visible as incomplete, error or overdue status. Inspect per-source checks and retain freshness warnings in investigations and exports. An up-to-date index does not prove that ungoverned activity was captured.

Troubleshooting

• 401: check expiry or revocation and authenticate again.
• Permission denied: check whoami and consent scopes. Metadata access is not retained-content or export access.
• 405 when opening /mcp in a browser: this is a protocol endpoint, not a web page. Connect through an MCP client.
• No retained text: check capture opt-in and retention; unavailable content is not a clean incident history.

The local haltstate-mcp stdio package is an unpublished source candidate, not a registry-installed alternative. This guide does not certify Claude Desktop, ChatGPT or every MCP client. For support, provide client/version, time and a sanitized error, never credentials or message contents.