# pulse-mcp `pulse-mcp` is the Model Context Protocol (MCP) adapter for Pulse Intelligence. It lets Claude Desktop, Claude Code, Codex, OpenCode and any other MCP-speaking client ask Pulse what it has seen while it monitors: what changed across the fleet and when (`list_recent_changes`), how a resource's metrics moved (`get_metric_history`), and where to look first (`get_fleet_context`, `get_resource_context`). A `monitoring:read` token covers those reads. With more scopes it exposes the same governed operations substrate that Pulse Assistant uses inside the app: list findings, set operator intent, and plan, approve and run governed actions. ## Pulse Intelligence surface contract - **Pulse Intelligence Core**: Canonical context, governed actions, safety gates, approval state, action audit, and verification shared by Pulse Assistant, Pulse MCP, and Pulse Patrol. - **Pulse Patrol**: Patrol is the first-party operations surface: it checks infrastructure, investigates issues, follows the chosen Patrol mode before acting, verifies outcomes, and records what happened. - **Pulse Assistant** (the native Pulse surface): The chat surface Pulse Mobile uses for operator questions over the same governed tools, approvals, and verification; the in-app web chat window is retired. Affordances: tools. - **Pulse MCP**: The external-agent adapter that projects canonical Pulse Intelligence capabilities as MCP tools. Affordances: tools, resources, prompts, and capability metadata. The adapter is manifest-driven. Every tool it exposes is one entry in Pulse's canonical capabilities manifest at `/api/agent/capabilities`. Adding a request/response capability to the manifest-owned Pulse MCP surface tool contract extends this server automatically. There is no hardcoded tool list to keep in sync, and there is no separate MCP-only action path to maintain beside Pulse Assistant. `tools/list` uses the shared Pulse Intelligence projection to expose the manifest metadata in each tool description, including route, auth scope, action mode (`read`, `mixed`, `write`), approval policy (`scope_only`, `action_plan`), request/response shape, and stable error codes. Operator-state writes plus governed action and finding lifecycle tools also expose typed `inputSchema` definitions for their top-level arguments, including stable enums for criticality, approval decisions, and dismissal reasons. The same shared projection exposes `resources/list` and `resources/read` when the manifest contains the canonical fleet and per-resource context capabilities. Resource URIs use `pulse://resource/` and `resources/read` returns the same JSON bundle as `get_resource_context`. It also exposes `prompts/list` and `prompts/get` from the manifest-owned `workflowPrompts` catalogue. Those prompts are workflow hints over the manifest tools and resource URIs, not a separate MCP playbook layer. ## Install Install the adapter on the machine running your MCP client, not on every monitored host. Installation needs no Pulse token. ### 1. Verified, saved installer (recommended) Follow the [saved-installer verification steps](../../docs/AGENT_SUBSTRATE.md#install-the-mcp-adapter-safely) for Unix or Windows. They download one published release's installer to a new directory and verify the release and exact saved asset before you review or execute it. Do not pipe a remote script into Bash or PowerShell. The installer detects your platform, verifies Pulse's signed checksum manifest and the matching binary's SHA256, and places it at `~/.local/bin/pulse-mcp` (or `/usr/local/bin/pulse-mcp` if `~/.local/bin` is not writable). Override the install location with `PULSE_MCP_BIN_DIR=/some/path` or pin the exact published tag with `PULSE_MCP_VERSION=vX.Y.Z` (PowerShell: `-Version vX.Y.Z`). Without that pin it downloads the latest release, which need not be the release whose installer you just verified. Windows installs to `%LOCALAPPDATA%\pulse-mcp` by default. Keep OS security controls enabled. ### 2. Download from a GitHub Release Pick the binary that matches your platform from the Pulse release assets: - `pulse-mcp-darwin-arm64`, `pulse-mcp-darwin-amd64` for macOS - `pulse-mcp-linux-amd64`, `pulse-mcp-linux-arm64`, `pulse-mcp-linux-armv7` for Linux - `pulse-mcp-windows-amd64.exe` for Windows - (full matrix on the release page) Save it without running it. Use the same release and asset verification steps above, substituting the exact binary filename for the installer. A SHA256 match against an unauthenticated `checksums.txt` alone is not verification. Only after verification, `chmod +x` it on Unix and put it on your `PATH`. If macOS Gatekeeper, Windows policy or another security control blocks launch, keep the warning and use your administrator's normal software approval path. Pulse's detached release signature is not macOS notarization or Windows Authenticode; do not remove quarantine or weaken execution policy as a troubleshooting shortcut. ### 3. Build from source If you have Go installed: ```sh go install github.com/rcourtman/pulse-go-rewrite/cmd/pulse-mcp@latest ``` Or from a Pulse repo checkout: ```sh go build -o pulse-mcp ./cmd/pulse-mcp ``` Drop the binary somewhere on your `PATH` (or reference its full path in the config snippets below). ## Quick start ### 1. Get the binary Use any of the install paths above. The rest of this guide assumes `pulse-mcp` is on your `PATH`. ### 2. Mint an API token Pulse fetches the live capabilities manifest first, and every tool description includes its required auth scope. Start with a dedicated, suitably expiring `monitoring:read` token, retaining its organisation/resource restrictions. The whole-surface scope union below is **not a recommended default or the minimum for read-only use**: `monitoring:read`, `monitoring:write`, `settings:read`, `settings:write`, `ai:execute`, `actions:plan`, `actions:approve`, and `actions:execute` Grant additional scopes only for the specific workflow you intend to delegate, not to make every tool callable or an all-scope readiness indicator pass. `monitoring:write` can change operator state without the action-plan approval loop, and `settings:write` can change infrastructure configuration. Planning, approval and execution have separate action scopes; the legacy `ai:execute` scope also permits those stages. Omitting it is not a control boundary if you still grant `actions:approve` or `actions:execute`. A scope alone does not bypass actor binding, permissions, separation of duties, step-up or live readiness. Mint the token in **Settings → API Access** and follow the [read-only connection and action boundaries](../../docs/AGENT_SUBSTRATE.md#connect-without-granting-control). A tool listing is not permission to call every listed tool. ### 3. Wire it into your client **The generated snippets below contain placeholders, not secret storage.** Keep real tokens in your client's private, user-local configuration or supported secret store, outside shared projects and repositories. Do not put a real token in a project-shared `.mcp.json` or `opencode.json`, command argument, URL or transcript. Do not export a token through a shell command containing its value. The adapter reads its environment; the client process and local administrators can still read that environment. Use only a client and model provider permitted to receive the returned infrastructure context, findings and action output. `http://localhost:7655` applies only when the client runs on the Pulse host. Otherwise use your existing verified HTTPS origin and preserve the proxy's access policy. Do not expose the backend or disable certificate verification to make a desktop client connect. Revoke an unused or exposed token in **API Access**; deleting the client configuration alone does not revoke it. Most MCP clients need the same manifest-owned runtime facts: server name `pulse`, command `pulse-mcp`, base URL flag `--base-url`, default URL `http://localhost:7655`, and token environment variable `PULSE_API_TOKEN`. The generated examples below cover the currently declared config families: `OpenCode`, `Claude-style clients`, and `custom MCP clients`. If your client uses a different outer config format, keep those runtime facts and adapt only the wrapper. #### OpenCode Uses OpenCode's top-level mcp object. Add this to `opencode.json`, `opencode.jsonc`, and `~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "pulse": { "type": "local", "command": ["pulse-mcp", "--base-url", "http://localhost:7655"], "enabled": true, "environment": { "PULSE_API_TOKEN": "your-token-here" } } } } ``` Restart OpenCode or reload its config after saving. Pulse tools appear under the `pulse` MCP server name. #### Claude-style clients Uses the common mcpServers object supported by Claude Desktop and Claude Code. Use this shape for `Claude Desktop` and `Claude Code` in `~/Library/Application Support/Claude/claude_desktop_config.json` and `.mcp.json`: ```json { "mcpServers": { "pulse": { "command": "pulse-mcp", "args": ["--base-url", "http://localhost:7655"], "env": { "PULSE_API_TOKEN": "your-token-here" } } } } ``` Restart your client after saving the config. If the client cannot resolve `pulse-mcp` from `PATH`, use the full binary path. #### custom MCP clients Keeps the Pulse MCP command, base URL flag, and token environment variable while adapting the outer client config shape. Use command `pulse-mcp`, pass `--base-url http://localhost:7655`, set `PULSE_API_TOKEN` to the API token, and keep the server name `pulse` when the client asks for one. ## Configuration | Flag | Default | Purpose | | ---- | ------- | ------- | | `--base-url` | `http://localhost:7655` | Pulse instance to talk to | | `--token-env` | `PULSE_API_TOKEN` | Env var holding the API token | | `--emit-notifications` | `false` | Translate Pulse SSE events into JSON-RPC notifications on stdout | The token is read from an environment variable, never a token flag, keeping it out of command arguments. This does not make the environment or the client's saved configuration inaccessible to local administrators. ### About `--emit-notifications` When enabled, the server opens a long-lived connection to `/api/agent/events` after `initialize` and writes a JSON-RPC notification on stdout for every non-transport event: ```json { "jsonrpc": "2.0", "method": "notifications/finding.created", "params": { ... } } { "jsonrpc": "2.0", "method": "notifications/approval.pending", "params": { ... } } { "jsonrpc": "2.0", "method": "notifications/action.completed", "params": { ... } } { "jsonrpc": "2.0", "method": "notifications/alert.fired", "params": { ... } } { "jsonrpc": "2.0", "method": "notifications/alert.resolved", "params": { ... } } { "jsonrpc": "2.0", "method": "notifications/resource.status_changed", "params": { ... } } ``` The `params` object is the SSE event's `data` payload verbatim, so an agent that already knows the substrate's wire shape sees identical content to what an HTTP SSE consumer would. Transport plumbing (`stream.connected`, `heartbeat`) is filtered out. `alert.fired`, `alert.resolved` and `resource.status_changed` carry the canonical `resourceId`, resource name and type, and the `changeId` and `kind` that `list_recent_changes` returns for the same change, so an agent can read the surrounding history. They carry the alert identifier, type and level, or the status `from` and `to`, never alert message or command text. A resource's status changes within 30 seconds of the last announced one fold into a single event with `coalescedTransitions`; a flap that ends where it started is not announced. Pulse announces changes as it records them; it does not replay old alert history on restart, and an event dropped for a slow client is still readable through `list_recent_changes`. `action.completed` also covers failed or refused terminal actions; its name alone is not a successful dispatch or recovery receipt. Inspect the result and verification evidence. Missing checks or `ran: false` do not establish the intended state. Even a verified check establishes only that postcondition at its recorded time. After a timeout or lost response, a change may already have happened: retain the action identity and inspect existing context/history rather than executing again. See [outcome interpretation](../../docs/AGENT_SUBSTRATE.md#read-action-outcomes-without-repeating-them). It is off by default because not every MCP client surfaces server-initiated notifications. Enable it when wiring an autonomous agent that processes the JSON-RPC stream programmatically. Claude Desktop today does not surface arbitrary `notifications/*` methods in the chat UI; if your client falls in that category, leave the flag off and consume the SSE stream directly. When `--emit-notifications` is on, the `initialize` response advertises the supported event kinds under `capabilities.experimental.pulseNotifications.kinds`. That list is projected from the shared Pulse Intelligence event vocabulary, so it stays aligned with `/api/agent/events`. Clients that don't understand the experimental block ignore it silently. ## What the tools do The exact request/response tool set is whatever your Pulse instance's manifest declares. The generated inventory below reflects the canonical manifest in this checkout; run `tools/list` from your MCP client to see the live set. **Context (read-only):** - `get_resource_context` (Get resource context, `GET /api/agent/resource-context/{resourceId}`, scope `monitoring:read`, mode `read`, approval `scope_only`): Return the situated picture of a resource — identity, operator-set state with maintenance-window-active flag, active findings, pending approvals scoped to this resource, recent actions including refused dispatches. Command fields are redacted for monitoring-read API tokens unless the token also has ai:execute. - `list_resource_capabilities` (List resource capabilities, `GET /api/agent/resource-capabilities/{resourceId}`, scope `monitoring:read`, mode `read`, approval `scope_only`): Return the structured governed capabilities a resource advertises (name, type, approval level, platform, and full parameter schemas). Companion to get_resource_context, which renders capabilities as count-limited prose; this is the structured surface an agent reads before calling plan_action so it can populate capabilityName and params without guessing. A resource with no advertised capabilities returns an empty array. - `get_fleet_context` (Get fleet context, `GET /api/agent/fleet-context`, scope `monitoring:read`, mode `read`, approval `scope_only`): Return a thin per-resource triage rollup across every resource visible to the org — identity, operator flags (intentionallyOffline, neverAutoRemediate, maintenanceWindowActive), per-severity finding counts (total/critical/warning/info), and pending-approval count. One read for 'where do I focus?'; follow up via get_resource_context for depth. Optional additive filters (hasFindings, severity, technology, resourceType) narrow the result to a relevant subset so agents triaging a large fleet do not receive or page through healthy resources. - `list_recent_changes` (List recent changes, `GET /api/agent/changes`, scope `monitoring:read`, mode `read`, approval `scope_only`): Return what Pulse observed changing across the fleet, newest first: state transitions, restarts, configuration and relationship changes, alerts fired, acknowledged, snoozed and resolved, and commands or runbooks run. One read for 'what happened since last night?'; optional filters (since, before, resourceId, kind, sourceType) narrow it. Only changes Pulse observed are listed, so a gap is not proof that nothing happened. Results are capped, and truncated says when more matched. Command text, output and runbook messages are redacted for monitoring-read API tokens unless the token also has ai:execute. - `get_metric_history` (Get metric history, `GET /api/agent/metric-history`, scope `monitoring:read`, mode `read`, approval `scope_only`): Return how one resource's metrics moved over a window, from the history Pulse records while it monitors: 'did this disk fill gradually or suddenly?', 'was memory climbing before the restart?'. Pass the canonical resourceId from get_fleet_context, list_recent_changes or get_resource_context. Omit metric to get every metric the resource records, which also tells you their names. Points are averaged into about maxPoints buckets (window edges can add one), each with min and max. Windows go up to 90d and return whatever the install's storage retention still keeps. - `get_patrol_control_status` (Get Patrol work status, `GET /api/agent/patrol-control/status`, scope `monitoring:read`, mode `read`, approval `scope_only`): Return the current content-safe Patrol work status: Patrol issue evidence, pending approvals, governed decisions/actions, verified outcomes, Patrol control outcome evidence, compatibility aliases, and optional MCP readiness. The payload is count-only and deliberately omits finding ids, action ids, prompts, commands, resource names, and output. **Operator state (per-resource intent):** - `get_operator_state` (Get operator state, `GET /api/resources/{resourceId}/operator-state`, scope `monitoring:read`, mode `read`, approval `scope_only`): Read the operator-set monitoring mode, lifecycle state, remediation lock, maintenance window, and criticality for a resource. - `set_operator_state` (Set operator state, `PUT /api/resources/{resourceId}/operator-state`, scope `monitoring:write`, mode `write`, approval `scope_only`): Replace the operator-set state for a resource. URL canonicalId wins over body; server populates setAt and setBy from the authenticated identity. - `clear_operator_state` (Clear operator state, `DELETE /api/resources/{resourceId}/operator-state`, scope `monitoring:write`, mode `write`, approval `scope_only`): Remove any operator-set state for a resource. Idempotent — succeeds whether or not an entry was present. **Findings (Patrol lifecycle):** - `list_findings` (List findings, `GET /api/ai/patrol/findings`, scope `ai:execute`, mode `read`, approval `scope_only`): List all Patrol findings (active, dismissed, resolved). Filter client-side on returned shape. - `acknowledge_finding` (Acknowledge finding, `POST /api/ai/patrol/acknowledge`, scope `ai:execute`, mode `write`, approval `scope_only`): Mark a finding as seen but keep it visible. Auto-resolves when the underlying condition clears. - `snooze_finding` (Snooze finding, `POST /api/ai/patrol/snooze`, scope `ai:execute`, mode `write`, approval `scope_only`): Hide a finding for a defined duration in hours. - `dismiss_finding` (Dismiss finding, `POST /api/ai/patrol/dismiss`, scope `ai:execute`, mode `write`, approval `scope_only`): Dismiss a finding with a reason: not_an_issue (permanent suppression), expected_behavior (acknowledged forever), or will_fix_later (7-day reminder commitment). - `resolve_finding` (Resolve finding, `POST /api/ai/patrol/resolve`, scope `ai:execute`, mode `write`, approval `scope_only`): Manually mark a finding as resolved when the underlying issue has been fixed out-of-band. **Actions (governed plan/approval/execute):** - `plan_action` (Plan action, `POST /api/actions/plan`, scope `actions:plan`, mode `write`, approval `action_plan`): Plan an action against a resource. The planner validates the request, looks up the capability on the resource, checks executor-owned live availability, and returns an ActionPlan with the approval policy, blast radius, plan hash, and preflight summary. The plan is persisted to the audit history at the planned/pending state only after the live availability check passes, so subsequent decide_action and execute_action calls can reference it by id. Plan-and-execute is a two-step flow when the resulting plan requires approval, one-step otherwise. - `decide_action` (Decide action, `POST /api/actions/{actionId}/decision`, scope `actions:approve`, mode `write`, approval `action_plan`): Record an approval decision (approved or rejected) on a previously planned action. The actor is taken from the authenticated identity; an explicit reason can be passed in the body. Approval rechecks current expiry, policy, executor, resource-contract, and executor-owned availability gates before persistence, while rejection remains available when readiness is false. An exact retry returns the authoritative persisted decision without adding an approval or lifecycle event; a conflicting retry fails closed. - `execute_action` (Execute action, `POST /api/actions/{actionId}/execute`, scope `actions:execute`, mode `write`, approval `action_plan`): Execute a previously planned and (when required) approved action. Returns the persisted audit record with the execution result attached. Refuses with stable codes when the action is in the wrong lifecycle state (action_not_approved, action_already_executing, action_execution_final, action_dry_run_only, action_plan_expired), when executor-owned live readiness is no longer available (action_execution_unavailable), when the approved plan no longer matches the current resource/capability contract (action_plan_drift), when the target is operator-locked against automated remediation (resource_remediation_locked), or when the API instance has no executor wired (action_executor_unavailable). Both human and automatic policy execution recheck readiness before dispatch admission. action.completed SSE events fire on every terminal state so agents watching the stream do not need to poll this endpoint after dispatch. **Provisioning (infrastructure onboarding):** - `list_nodes` (List nodes, `GET /api/config/nodes`, scope `settings:read`, mode `read`, approval `scope_only`): List configured infrastructure sources that Pulse can monitor or manage. Credential secret values are redacted; use the returned id with update_node, remove_node, test_node_connection, or refresh_node_cluster_membership. - `add_node` (Add node, `POST /api/config/nodes`, scope `settings:write`, mode `write`, approval `scope_only`): Add a Proxmox VE, Proxmox Backup Server, or Proxmox Mail Gateway source to Pulse after credentials have been collected, generated, or approved. - `update_node` (Update node, `PUT /api/config/nodes/{nodeId}`, scope `settings:write`, mode `write`, approval `scope_only`): Update a configured infrastructure source. Omitted fields preserve the current value; tokenValue or password only changes when supplied. - `remove_node` (Remove node, `DELETE /api/config/nodes/{nodeId}`, scope `settings:write`, mode `write`, approval `scope_only`): Remove a configured infrastructure source from Pulse by node id. - `test_node_credentials` (Test node credentials, `POST /api/config/nodes/test-config`, scope `settings:write`, mode `mixed`, approval `scope_only`): Validate proposed source credentials and connection details without saving them to Pulse. - `test_node_connection` (Test node connection, `POST /api/config/nodes/{nodeId}/test`, scope `settings:write`, mode `mixed`, approval `scope_only`): Validate the saved connection for an existing configured infrastructure source. - `refresh_node_cluster_membership` (Refresh node cluster membership, `POST /api/config/nodes/{nodeId}/refresh-cluster`, scope `settings:write`, mode `write`, approval `scope_only`): Re-detect Proxmox VE cluster membership and endpoint metadata for a configured source. - `discover_lan` (Discover LAN, `POST /api/discover`, scope `settings:write`, mode `mixed`, approval `scope_only`): Scan a subnet, or return cached scan results, to find candidate infrastructure hosts before deciding which sources to add to Pulse. ## Workflow prompts Clients that support MCP prompts can also discover Pulse workflow hints. They are projected from the manifest-owned `workflowPrompts` catalogue: - `pulse_triage_fleet` (Triage fleet): Triage the Pulse fleet using the canonical fleet context capability, then choose where deeper investigation is warranted. - `pulse_operations_loop` (Ask Patrol to handle an issue): Have Patrol investigate active findings, follow the configured Patrol mode, take approved actions, verify the outcome, and record what happened. - `pulse_investigate_resource` (Investigate resource; required argument `resourceId`): Investigate one Pulse resource using the canonical resource context capability and resource URI projection. - `pulse_review_finding` (Review finding; required argument `finding_id`): Review one Patrol finding and propose the safest governed next step. Run `prompts/list` from your MCP client to see the live prompt set. ## Resource browser Clients that support MCP resources can call `resources/list` to browse the same canonical resource IDs returned by `get_fleet_context`, then `resources/read` to fetch the full `get_resource_context` JSON bundle for one resource. Example URI: ```text pulse://resource/vm:101 ``` The adapter does not maintain a separate resource registry. The resource list is rebuilt through the live fleet-context capability, and each read is a normal per-resource context capability call with the same auth scope, redaction rules, and error envelope as the tool surface. ## Stable error envelope Every Pulse error reaches your agent verbatim, in this shape: ```json { "error": "", "message": "" } ``` The MCP tool result wraps that JSON in a text content block with `isError: true`. Branch on `error` (snake_case stable codes); use `message` for surfacing to humans, never for branching. Capability-specific stable codes are advertised by the manifest: - `get_resource_context`: `resource_not_found` - `list_resource_capabilities`: `resource_not_found` - `get_operator_state`: `operator_state_not_set` - `set_operator_state`: `operator_state_invalid` - `acknowledge_finding`: `invalid_finding_request`, `finding_not_found`, `finding_action_not_allowed`, and `patrol_unavailable` - `snooze_finding`: `invalid_finding_request`, `finding_not_found`, `finding_action_not_allowed`, and `patrol_unavailable` - `dismiss_finding`: `invalid_finding_request`, `finding_not_found`, `finding_action_not_allowed`, and `patrol_unavailable` - `resolve_finding`: `invalid_finding_request`, `finding_not_found`, `finding_action_not_allowed`, and `patrol_unavailable` - `plan_action`: `invalid_action_request`, `action_request_conflict`, `mock_mode_enabled`, `action_actor_unavailable`, `resource_not_found`, `capability_not_found`, `action_execution_unavailable`, and `action_refresh_not_allowed` - `decide_action`: `mock_mode_enabled`, `missing_id`, `invalid_id`, `invalid_action_decision`, `action_not_found`, `action_not_pending`, `action_plan_expired`, `action_plan_identity_mismatch`, `action_actor_unavailable`, `action_approval_forbidden`, `action_step_up_unavailable`, `action_decision_conflict`, `action_separation_required`, `action_replan_required`, `action_execution_unavailable`, `action_plan_drift`, `action_emergency_stop`, `action_dry_run_only`, `resource_remediation_locked`, `action_executor_unavailable`, and `action_execution_availability_failed` - `execute_action`: `mock_mode_enabled`, `missing_id`, `invalid_id`, `invalid_action_execution`, `action_not_found`, `action_not_approved`, `action_already_executing`, `action_execution_final`, `action_dry_run_only`, `action_plan_expired`, `action_execution_unavailable`, `action_plan_drift`, `action_emergency_stop`, `action_plan_identity_mismatch`, `resource_remediation_locked`, `action_executor_unavailable`, `action_actor_unavailable`, `action_execution_forbidden`, `action_not_executing`, and `action_replan_required` Cross-cutting codes from the auth / multi-tenant middleware (`invalid_org`, `org_suspended`, `access_denied`) can apply to any authenticated tool call. ## Known limitations - **No `subscribe_events` tool.** SSE streaming does not fit the MCP request/response tool shape, so the adapter does not expose the `/api/agent/events` stream as a callable tool. Agents that want real-time push have two options: consume the SSE stream directly via HTTP (works with any MCP client), or run with `--emit-notifications` so the bridge translates SSE events into JSON-RPC notifications on the stdio channel (requires a client that processes server-initiated notifications). - **Manifest is fetched once.** The server fetches `/api/agent/ capabilities` at startup and does not refresh during the process lifetime. Restart `pulse-mcp` to pick up new capabilities after upgrading Pulse. ## Troubleshooting **"env var PULSE_API_TOKEN is empty" on startup.** The adapter refuses to start without a token. Mint one in Settings and make sure your client's `env` block (or shell environment) sets `PULSE_API_TOKEN`. **"manifest GET returned 401" on startup.** Discovery is supposed to be unauthenticated. If your Pulse instance is behind a reverse proxy that adds auth in front of the public paths, the proxy may be enforcing its own access policy. Public inside Pulse does not mean publicly reachable through your proxy. Check the existing authorised client path; do not exempt discovery or health from proxy authentication, expose a backend or copy a browser session cookie into the adapter to bypass that policy. The environment API token authenticates Pulse, not an unrelated proxy login. **Tools work, but a write or action tool returns 403 access_denied.** Read the relevant error and live tool metadata privately. A 403 is not by itself proof of a missing scope: permissions, organisation/resource boundaries or action policy can also refuse it. If the client is meant to be read-only, leave it denied. Do not add `ai:execute`, approval or execution scopes merely to clear an error. For an intended write, check the specific scope and authority against [the separate action steps](../../docs/API.md#unified-action-planning); operator-state writes instead use `monitoring:write` and scope-only policy. Do not run a write, induce a finding or enable Debug as a connectivity test. **Tools list is empty.** The adapter filters `subscribe_events` out (it is not request/response shaped). If literally nothing else shows up, your Pulse instance's manifest may be empty or the client may not have completed initialisation. Inspect the existing manifest and client error privately before diagnosing it. Use the [bounded private-response HTTP reads](../../docs/AGENT_SUBSTRATE.md#connect-without-granting-control), not credential-bearing logs, a public backend or an action as a probe. ## Implementation notes The adapter binary is intentionally thin. It speaks JSON-RPC 2.0 over stdio with line-delimited framing, logs to stderr to keep the JSON-RPC channel on stdout clean, and delegates method semantics, tool projection, call-argument normalization, HTTP projection, and result envelopes to the shared Pulse Intelligence contracts in `internal/agentcapabilities`. Tool input schemas come from the manifest-owned JSON Schema when present; the shared projection only falls back to deriving path placeholders and a permissive body object for capabilities that have not yet authored a stricter schema. The companion worked example, `cmd/agent-probe`, walks the same substrate as a plain HTTP client and is a useful reference for anyone building a non-MCP integration. Together the two binaries demonstrate Pulse Intelligence's external-agent profiles: stdio MCP and direct HTTP API. Pulse Patrol is the first-party operations surface over the same governed contracts, and Pulse has no in-app chat window; `pulse-mcp` is how you ask about your infrastructure from an external agent host.