@craze0/agentpulse-mcp
v0.4.0
Published
Standalone MCP server for AgentPulse — monitor and orchestrate AI coding agent sessions from any MCP-compatible client.
Maintainers
Readme
@craze0/agentpulse-mcp
Standalone MCP (Model Context Protocol) server for AgentPulse — talk to any running AgentPulse instance from Claude Code, Codex CLI, or any other MCP-compatible client, without cloning the AgentPulse repo.
Canonical source: this package is published from
github.com/jstuart0/agentpulse, directorypackages/agentpulse-mcp/. Verify you're installing@craze0/agentpulse-mcpfrom npm's canonical listing before trusting it — near-miss names (the unscopedagentpulse-mcp,agent-pulse-mcp, anything under the@agentpulsescope, …) are typosquat vectors once a package name is public. The MCP server can also run from a checkout of the main repo (agentpulse mcp serve/agentpulse mcp install) — seedocs/MCP.mdthere.
Compatibility: requires AgentPulse main (the future 0.6.0 release) or later — specifically, the release whose GET /auth/me reports API-key scopes. Older servers fail fast at startup with an upgrade message rather than silently registering a broken tool set.
Quickstart
# Mint an observe-only (read-only) key and print client config — the default, safe choice
npx @craze0/agentpulse-mcp install --mint my-agent
# Mint a manage-scoped key that can also launch/steer/decide (read Security first)
npx @craze0/agentpulse-mcp install --mint my-agent --orchestrate
# Reuse an existing key instead of minting a new one
npx @craze0/agentpulse-mcp install --key ap_your_existing_key
# Point at a remote AgentPulse instance
npx @craze0/agentpulse-mcp install --mint my-agent --url https://agentpulse.example.cominstall never writes files for you — it prints three ready-to-paste blocks (Claude Code one-shot command, .mcp.json, Codex config.toml, each pinned to this package's own installed version) plus an export AGENTPULSE_API_KEY=... line. Reusing --key runs a preflight against /auth/me first and refuses to print a config for a key that doesn't actually hold the scope you asked for.
To run the server directly (e.g. you already have a key and want to write the client config by hand):
npx @craze0/agentpulse-mcp servebunx @craze0/agentpulse-mcp serve works identically if you have Bun installed. It reads AGENTPULSE_URL (defaults to http://localhost:3000) and AGENTPULSE_API_KEY from the environment and speaks MCP over stdio.
Tool catalog
Tools span three tiers: observe-scoped reads, additional manage-only reads (their DTOs carry secrets or operator-authored content), and manage-scoped mutations — plus 3 read-only @-mentionable Claude Code resources. See the full per-tool catalog, wrapped-endpoint table, and the list of deliberately-excluded operations in the main repo's docs/MCP.md — this package's tool set, schemas, output caps, and scope gating are byte-identical to what's documented there.
list_hosts returns each supervisor host as the server reports it, including excludeRulesState: "invalid" when the exclude file on that host has an error and its supervisor is sending no session data until it is fixed, otherwise null or absent (the server keeps no other state). Each host may also carry outbox (a host's offline outbox as it last reported it): { pending, oldestPendingAt, lastFlushAt, lastFlushDelivered, lastFlushLost }, with pending the reports the host is holding for when the server is reachable and the last four describing its most recent catch-up. It is absent when the host has nothing to show or runs an older supervisor. It is the last value the host reported and is never aged by the server: read it only while the host's heartbeatLeaseExpiresAt is in the future, or you will report a catch-up that ended long ago (or never finished, if the host is gone). Session events (get_session, get_session_timeline, get_event_context) may carry occurredAt, when the sending supervisor says the event happened; it is omitted when unknown and is display only, so order by id, not by it. An event replayed after an outage has createdAt later than occurredAt; occurredAt can run backwards across such events.
Approvals for managed sessions (Codex, and Claude Code sessions continued in AgentPulse). manage keys also get list_pending_approvals (read) and decline_approval (decline one). There is deliberately no accept: accepting a command is for a signed-in person in the dashboard, and the server refuses every API key, because a key in an agent's own configuration that could accept would let the agent approve itself. A server that predates the feature answers both tools with "This AgentPulse server doesn't support approvals for managed sessions."; the rest of the package works against it unchanged.
Team mode. Against a server in team mode, a key acts as its owner (a member, or an admin if the owner is one), and an ownerless service key acts as a member unless an admin has kept it as an admin service key. observe keys still read every session; owner filtering is a view, not access control. list_sessions and get_stats accept owner (me, a user id, unassigned, service, all) and return an error instead of a list when the server's ownerScope echo is missing or doesn't match what was asked, because a server that predates owner scoping would ignore the filter and answer with everyone's sessions. They also accept host (an exact machine name) or no_host (sessions with no machine) and apply the same rule to the server's hostFilter echo; a machine name is self-declared and is a view, not access control. prompt_session, stop_session, retry_launch and launch_agent aren't owner-checked; update_session needs the session's owner or an admin, field by field. A launch the host's supervisor refuses because the directory is excluded fails with the same generic message as a trusted-roots refusal. GET /users/directory (REST only, no tool) is readable by observe keys and returns id, displayName, disabled and authSource for everyone who can own something. Details: docs/MCP.md.
Security
This is the load-bearing section. Read it before minting a manage-scoped key.
requiresUserInteraction (rUI) is a host-side convention, not a protocol-enforced gate. AgentPulse stamps _meta["anthropic/requiresUserInteraction"]: true on every mutating tool. Claude Code's UI honors that flag and prompts you before running the tool. Codex CLI does not — and Codex's own global approval_policy setting does not gate MCP tool calls either (confirmed against codex#15437; even approval_policy = "never" still let MCP writes through). The only real gate for Codex is the per-server default_tools_approval_mode key under [mcp_servers.agentpulse], which install --orchestrate emits as "writes" (auto-runs read-only tools, prompts before mutating ones). Any other scripted or headless MCP client honors neither mechanism unless you've built confirmation into it yourself — a mutating tool call executes immediately.
A manage-scoped key is unattended, full operator control. It can spawn and kill agent processes, inject prompts into a live session as if you'd typed them, and approve or deny items in the human-in-the-loop review queue — bypassing the human review that queue exists to provide. Mint observe (the default) unless you specifically need orchestration, and treat a manage key like a production infrastructure credential, not a convenience toggle.
Session transcripts are visible to observe keys, and may contain whatever the observed agent itself printed — including incidental secrets in tool_input/tool_response payloads. This is inherent to observability (AgentPulse doesn't redact agent-authored transcript content on this read path today) and is accepted as residual risk, not a bug. observe is only guaranteed secret-free at the AgentPulse-held-credential boundary (env vars, launch specs, claim tokens, HITL/action-request payloads).
Point AGENTPULSE_URL only at a server you control. The client sends your Bearer API key to whatever host that URL resolves to; serve prints a warning to stderr (never blocks) when the resolved host isn't localhost/127.0.0.1/::1.
DISABLE_AUTH=true plus a manage-scoped MCP key is no scope boundary at all. Under DISABLE_AUTH, every caller (including this MCP server) is treated as fully authenticated with every scope. This combination is intended for trusted local use only.
Supply-chain: exact-pin every emitted config, review before bumping
Every config install emits (claude mcp add, .mcp.json, config.toml) pins this package to an exact version — @craze0/agentpulse-mcp@<version>, never a bare or ranged spec. This is a deliberate choice, not an oversight: an unpinned npx -y @craze0/agentpulse-mcp serve means a compromised npm publish silently reaches every fleet-control client on its next MCP-host restart, with zero review step. For a credential that can spawn/kill agents and approve human-in-the-loop review items, that's the wrong tradeoff.
If you're running a --orchestrate (manage-scoped) install: treat a version bump as a security-relevant change. Read the release before bumping the pin — re-run npx @craze0/agentpulse-mcp install (or hand-edit the @<version> in your existing config) only after reviewing what changed. Don't script an automatic bump for a manage-scoped client. observe-only installs carry lower stakes but the same discipline is still good hygiene.
Publishing itself uses npm trusted publishing (GitHub Actions OIDC) where available — no long-lived npm token exists that could be exfiltrated to push a malicious release; each publish carries provenance attestation you can verify (npm audit signatures, or the "Provenance" tab on the npm package page).
This package's own two runtime dependencies (@modelcontextprotocol/sdk, zod) are exact-pinned in package.json (no ^/~ range) for the same reason as the emitted-config pin above: a fleet-control package shouldn't auto-pull whatever a compromised transitive dependency's postinstall does on the next npm install just because a caret range happened to match a new publish. Bumping either dependency here is a reviewed, deliberate change, not an automatic one.
Hardening roadmap / known limitations
Tracked follow-ups in the main repo, not silently accepted gaps — these apply equally whether you run the server via this package or from a checkout:
- No env-var denylist on launch.
launch_agentand the underlying REST launch pipeline accept an arbitraryenvmap without rejecting known-dangerous names (LD_PRELOAD,NODE_OPTIONS,*_PROXY,*_API_KEY,*_TOKEN,*_SECRET, ...). - No per-action attribution. MCP-originated mutations record the same
requestedByas any other caller — there's noorigin: "mcp"tag distinguishing an MCP-driven launch/prompt/decide from a dashboard-driven one in the audit trail. - No rate limiting on mutating MCP tools. Nothing currently throttles repeated
launch_agent/prompt_session/etc. calls from a misbehaving or looping client. - No server-side HITL risk-threshold gate.
decide_hitl/decide_action_requestlet amanage-scoped key approve any HITL item, including ones a human would want to review personally for high-risk actions. Approving now sends the prompt to the agent (queued on a managed session whose host is connected, Codex sessions included, where it starts a new turn on the Codex thread); it is no longer only a record.prompt_sessionon a Codex session runs under that session's launch policy, andprompt_not_deliverablecan carryhost_upgrade_requiredormanaged_state(nothing is sent and the request stays open). In team mode the key still has to belong to the session's owner or an admin (a key with no owner is refused), andcontrol_busymeans nothing was sent and the call can be repeated. - No server-side recomputation of a submitted
launchSpec.POST /launchestrusts the client-suppliedlaunchSpecafter reloading the template by id rather than recomputing it fresh. agent_type: "copilot_cli"and"opencode"need a server at or above this package version.list_sessions'sagent_typefilter is validated client-side by this package's own zod enum (OBSERVED_AGENT_TYPE_ENUM, which acceptsclaude_code,codex_cli,copilot_cliandopencode; Copilot CLI and OpenCode are observed only and can't be launched). The server itself rejects an unrecognizedagent_typewith a400as of this release, but a server older than this release predates both Copilot CLI/OpenCode support and that validation, so its request handler treats an unknown value as an equality filter against nothing. Filtering bycopilot_clioropencodeagainst a server that old silently returns zero sessions rather than an error, which can look identical to "the filter didn't apply" from the client side. There's no client-side way to detect a server's actual feature set today; upgrading the server closes the gap.
Upgrading
Bump the pinned @<version> in whatever config you're using:
- Claude Code one-shot: re-run
npx @craze0/agentpulse-mcp install ...and re-paste theclaude mcp addcommand it prints. .mcp.json/~/.codex/config.toml: hand-edit the@craze0/agentpulse-mcp@<old-version>string to the new version (or re-runinstalland copy the block again).
For a manage-scoped install, read the release notes for the version you're bumping to before doing this (see Supply-chain above).
Environment variables
| Variable | Used by | Default |
|---|---|---|
| AGENTPULSE_URL | serve, install | http://localhost:3000 |
| AGENTPULSE_API_KEY | serve, and as an auth fallback for install --mint/--key | — |
Related
- Main repo: https://github.com/jstuart0/agentpulse
- In-repo canonical docs:
docs/MCP.md(full tool catalog, wrapped-endpoint table, deliberately-excluded operations) - License: MIT
