Claude Code MCP Server Monitoring with AgentCheck

If you need claude code mcp server monitoring, the hard part is not collecting more logs. The hard part is seeing what an agent actually did, which tools it called, and whether those calls violated local policy. AgentCheck is a wrapper for Claude Code that adds hook-based guardrails, records tool activity to JSONL, and applies YAML rule packs before actions run. That is useful when you are debugging MCP-connected workflows or trying to keep autonomous coding sessions bounded.

Why claude code mcp server monitoring matters

MCP servers widen the runtime surface area of an agent. A session that used to call a shell tool may now read from a database connector, inspect a repo service, or invoke custom internal utilities. For developers, that means failures become harder to reproduce. You need to know whether the bug came from prompt drift, a bad tool response, or an agent making a call it should not have made in the first place.

Good claude code mcp server monitoring should answer a few basic questions: which tool was called, with what arguments, in what order, and under which policy. AgentCheck is valuable because it focuses on those behavioral details rather than pretending all agent problems are observability problems. You still need normal system logs, but you also need an execution trail that maps to agent decisions.

Install and wrap Claude Code

AgentCheck installs as a global npm package from GitHub. The main operating model is straightforward: wrap the Claude Code process, attach rules, and emit logs in a format that is easy to grep, stream, or archive. JSONL is a practical choice because it works well with command-line tooling and does not require a separate collector just to get started.

npm install -g github:paprika-org/agentcheck

mkdir -p .agentcheck

cat > .agentcheck/rules.yaml <<'YAML'
rules:
  - id: block-destructive-shell
    match:
      tool: shell
      args_regex: "(rm -rf|git reset --hard)"
    action: deny

  - id: log-mcp-reads
    match:
      tool: mcp
    action: allow
YAML

agentcheck --rules .agentcheck/rules.yaml -- claude

The code above is intentionally minimal. In practice, you will want separate rule packs for local development, CI runs, and higher-risk environments. One limitation to state clearly: wrapping a process only governs what happens inside that wrapped execution path. If someone bypasses the wrapper, your monitoring and policy layer does not apply.

What AgentCheck gives you for MCP-heavy sessions

For MCP-backed workflows, AgentCheck adds two things that are usually missing from default agent runs: structured evidence and enforceable constraints. The JSONL log provides a sequence of tool events you can inspect after a run. That is enough to build simple incident reviews without adding a full tracing stack.

The rule-pack model is equally important. When an agent has access to shell tools and multiple MCP servers, “observe only” is often too weak. You may want to block destructive shell commands, allow read-only MCP calls, or force explicit review before a write path is used. This is where claude code mcp server monitoring becomes governance rather than just telemetry.

There are honest limits. AgentCheck does not magically understand the business meaning of every tool payload. If an MCP server exposes a write operation with an innocuous name, your rule pack still needs to classify it correctly. Monitoring quality depends on the clarity of your policies and how consistently the wrapped environment is used.

Designing useful rule packs and log workflows

Rule packs should start small. Deny obviously destructive actions, allow read paths, and log everything you are unsure about. Trying to encode a complete security policy on day one usually leads to brittle rules and false positives. For developer teams, a narrow pack that catches the top five dangerous patterns is often more useful than an ambitious pack nobody trusts.

For logs, keep them machine-readable and boring. JSONL works because you can inspect single lines during debugging and later ship the same files into a parser or SIEM. A useful pattern is to treat the agent log as an event stream and correlate it with shell history, CI metadata, or host-level audit logs. AgentCheck does not replace those systems; it gives you a behavior-focused layer that normal infrastructure logging usually misses.

Common mistakes

Pitfall 1: treating wrapper logs as complete security coverage. They are not. If a process can run outside AgentCheck, or if another tool path exists that does not pass through the wrapper, you have blind spots. Use OS permissions and environment isolation alongside rule packs.

Pitfall 2: writing rules that key only on tool names. That is often too coarse. A tool called through MCP might support both read and write operations. If your rules do not inspect arguments or operation types, you can accidentally allow more than intended.

Pitfall 3: logging everything without retention discipline. JSONL is easy to produce, which means it is also easy to accumulate sensitive operational detail. Decide early how long logs should live and who can read them.

Frequently Asked Questions

Does AgentCheck replace an MCP server?

No. AgentCheck does not implement the MCP protocol or serve tools itself. It wraps Claude Code processes, records tool activity, and enforces local rule packs around the existing agent runtime.

What do you actually get from the logs?

You get JSONL records of tool calls and related execution events. That makes it easier to reconstruct what happened during a session, correlate agent actions with failures, and feed the output into shell scripts or log pipelines.

Can rule packs stop dangerous commands?

Yes, within the scope of the wrapped process. Rule packs can constrain actions before they run, but they are not a substitute for operating system isolation, network controls, or repository permissions.

Is this enough for production-grade monitoring?

Usually it is one layer, not the whole stack. For production use, combine AgentCheck with host-level logging, CI policy checks, and access controls so monitoring does not depend on a single wrapper alone.