npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@craze0/agentpulse-mcp

v0.4.0

Published

Standalone MCP server for AgentPulse — monitor and orchestrate AI coding agent sessions from any MCP-compatible client.

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, directory packages/agentpulse-mcp/. Verify you're installing @craze0/agentpulse-mcp from npm's canonical listing before trusting it — near-miss names (the unscoped agentpulse-mcp, agent-pulse-mcp, anything under the @agentpulse scope, …) 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) — see docs/MCP.md there.

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.com

install 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 serve

bunx @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_agent and the underlying REST launch pipeline accept an arbitrary env map without rejecting known-dangerous names (LD_PRELOAD, NODE_OPTIONS, *_PROXY, *_API_KEY, *_TOKEN, *_SECRET, ...).
  • No per-action attribution. MCP-originated mutations record the same requestedBy as any other caller — there's no origin: "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_request let a manage-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_session on a Codex session runs under that session's launch policy, and prompt_not_deliverable can carry host_upgrade_required or managed_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), and control_busy means nothing was sent and the call can be repeated.
  • No server-side recomputation of a submitted launchSpec. POST /launches trusts the client-supplied launchSpec after 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's agent_type filter is validated client-side by this package's own zod enum (OBSERVED_AGENT_TYPE_ENUM, which accepts claude_code, codex_cli, copilot_cli and opencode; Copilot CLI and OpenCode are observed only and can't be launched). The server itself rejects an unrecognized agent_type with a 400 as 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 by copilot_cli or opencode against 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 the claude mcp add command it prints.
  • .mcp.json / ~/.codex/config.toml: hand-edit the @craze0/agentpulse-mcp@<old-version> string to the new version (or re-run install and 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