mcp-sentinel

A sentinel between an AI agent and MCP servers — polling long-running tasks on the agent's behalf so that token-costly status loops never enter the LLM inference path.

This is a monorepo: a harness-agnostic core (@gcszhn/mcp-sentinel-core) plus one thin plugin package per agent host.

Design principle

Zero MCP re-configuration. The sentinel never asks the user to configure MCP servers of its own. Installing the plugin is the whole setup — it discovers and reuses the MCP servers the harness already has, in whichever way that harness exposes them:

• From the host's MCP config — OpenCode. The plugin reads client.config.get().mcp and hands the resolved servers to the core, which owns the connection lifecycle. No extra MCP setup.
• Through the harness SDK — DeepSeek Harness. The plugin calls the mcp__<server>__<tool> tools already registered by @deepseek-ai/dsh-mcp-client via ctx.tools.execute. No extra MCP setup.
• As a harness-agnostic MCP CLI — any harness. mcp-sentinel mcp --harness <codex|opencode|custom> is a plain stdio MCP server that discovers the MCP servers the harness already exposes (codex mcp list --json, opencode debug config, or a --mcp-config file) and skips its own entry. No message notification channel — agents collect results with attach/status/read.

The agent immediately sees the MCP servers it already configured for that harness; there is no sentinel-specific MCP config, mock server, or demo wiring to maintain.

Supported harnesses

Install instructions and per-harness details live in each plugin's own README.

The shared core ships separately as @gcszhn/mcp-sentinel-core — see its README.

Motivation

When an agent submits a long-running job through an MCP tool, it must repeatedly call the server to check progress — each round-trip burns context window tokens.

sequenceDiagram
    participant A as Agent (LLM)
    participant M as MCP Server

    Note over A: Without sentinel
    A->>M: check status
    M-->>A: running...
    Note over A: token cost 💸
    A->>M: check status
    M-->>A: running...
    Note over A: token cost 💸
    A->>M: check status
    M-->>A: completed ✓
    Note over A: token cost 💸

mcp-sentinel moves the polling loop out of the agent and into the plugin runtime — 2 inference calls regardless of task duration.

sequenceDiagram
    participant A as Agent (LLM)
    participant S as Sentinel Plugin
    participant M as MCP Server

    A->>S: poll_mcp(server, tool, until)
    Note over A: token cost 💸 (once)

    loop silent polling (zero tokens)
        S->>M: call tool
        M-->>S: running...
        S->>S: evaluate condition
    end

    S->>M: call tool
    M-->>S: completed ✓
    S->>A: promptAsync(result)
    Note over A: token cost 💸 (once)

Configuration

Environment variables for controlling memory usage:

Both accept positive integers only. Zero, negative, or non-numeric values are treated as unlimited/disabled.

Tools

mcp_sentinel_poll

Submit a long-running MCP tool call and poll it at regular intervals until a condition is met. The sentinel polls silently (zero token cost) and notifies you when done.

Returns a sentinel ID immediately. The agent is notified when done (the delivery mechanism is host-specific).

args and until are native JSON values in the tool arguments — not JSON strings. interval is clamped to a minimum of 1000 ms; a positive timeout is clamped to a minimum of 5000 ms (values below the floor are raised).

mcp_sentinel_status

Check the status of sentinel tasks, list active tasks, or cancel a running task.

mcp_sentinel_attach

Block the agent, waiting for a sentinel task to complete. Sleeps and checks status internally with zero token cost. If interrupted by harness, the background async notification still fires normally.

mcp_sentinel_read

Read raw poll outputs from a sentinel task. Useful for debugging when a condition isn't matching — inspect actual MCP responses. Supports range-based pagination via offset.

Condition Model

Conditions are pure declarative data — no executable code, no injection surface.

// Simple comparison
{ "path": "status", "is": "eq", "value": "completed" }

// Array index access
{ "path": "[0].data.path", "is": "eq", "value": "found" }

// Regex match
{ "path": "log", "is": "match", "value": "^error" }

// Logical composition
{
  "and": [
    { "path": "status", "is": "eq", "value": "completed" },
    { "path": "tasks[0].exit_code", "is": "eq", "value": 0 }
  ]
}

Operators

Logical combinators

Path syntax

Uses property-access notation with array index support:

status               → obj.status
tasks[0].exit_code   → obj.tasks[0].exit_code
[0].data.path        → obj[0].data.path
items[2].name        → obj.items[2].name

Architecture

The project is a monorepo where each layer ships as its own npm package. The core knows nothing about any host; every harness is a thin, self-contained package layered on top of it.

Layers

Core / harness contract

The core exposes one uniform seam — ToolInvoker, a (server, tool, args) => Promise<unknown> function the engine calls once per poll — so each harness can plug in its own MCP access strategy without the core knowing which host it is running under.

// core — the uniform interface (harness-agnostic)
type ToolInvoker = (server: string, tool: string, args: Record<string, unknown>) => Promise<unknown>;

// the core engine accepts an invoker instead of reading host config itself
startSentinel(request, invoke: ToolInvoker): Promise<string>;

There are two ways to build the invoker:

1. Connection-pool mode — the harness parses the host's MCP config into a core McpConfig, builds a ServerResolver with makeServerResolver, and wraps it in makeConnectionInvoker, letting the core own the connection lifecycle.
2. External-invoker mode — the host already owns MCP (e.g. its own bridge registered tools on a tool registry); the harness passes its own (server, tool, args) => result function and the core never opens a connection.

MCP config discovery is the harness's job — different hosts fetch it differently (OpenCode via client.config.get().data mcp.* flat keys, Codex via codex mcp list --json, a --mcp-config file, …), and external-invoker hosts skip config discovery entirely.

The core's second seam is the notifier: a harness installs a completion callback with setNotifier(task, event), delivered through the host's message channel (OpenCode promptAsync, DeepSeek Harness Agent.followup). The core has no opinion on how a notification is rendered or pushed.

Adding a new harness

0. Develop it in its own git worktree — a new harness plugin is isolated from the core and from other harnesses; see AGENTS.md.
1. Create packages/<harness>/package.json named @gcszhn/mcp-sentinel-<harness>-plugin with a dependency on @gcszhn/mcp-sentinel-core.
2. Build a ToolInvoker: either parse the host's MCP config into a McpConfig and wrap it with makeConnectionInvoker(makeServerResolver(...)) (connection-pool mode), or pass a host-owned (server, tool, args) => result function (external-invoker mode).
3. Register the four tools, delegating to the core's handlePoll / handleStatus / handleAttach / handleRead handlers.
4. Install the notifier with setNotifier, pushing completions through the host's message channel (e.g. OpenCode promptAsync, DeepSeek Harness Agent.followup).

Data flow (core)

sequenceDiagram
    participant A as Agent (any host)
    participant H as Harness adapter
    participant C as Core engine
    participant M as MCP Server

    A->>H: poll(server, tool, until)
    H->>H: resolveServer()
    H->>C: startSentinel(...)
    C-->>H: sentinel ID
    H-->>A: acknowledgment

    loop every interval ms (zero tokens)
        C->>M: call tool(args)
        M-->>C: response
        C->>C: evaluateCondition(until, response)
    end

    C->>H: notify(completed)
    H->>A: host-specific completion push

Layout

packages/
  core/                         # @gcszhn/mcp-sentinel-core (zero host deps)
    src/
      engine.ts                 # startSentinel / cancel / getTask / getActive / cleanup
      tools.ts                  # handlePoll / handleStatus / handleAttach / handleRead
      condition.ts              # condition evaluator
      connection-pool.ts        # MCP client pool (@modelcontextprotocol/sdk)
      env.ts                    # SENTINEL_* env
      logger.ts                 # pluggable sink
      resolver.ts               # makeServerResolver (McpConfig → ServerResolver)
      types.ts                  # McpServerConfig / ServerResolver / Sentinel*
      index.ts                  # public barrel
    tests/
  opencode/                     # @gcszhn/mcp-sentinel-opencode-plugin
    src/
      plugin.ts                 # PluginModule entry
      index.ts                  # tool() definitions + promptAsync notifier
      config.ts                 # parseOpencodeMcpConfig (opencode `mcp` block) → McpConfig
    tests/
  deepseek-harness/             # @gcszhn/mcp-sentinel-deepseek-harness-plugin
    src/
      index.ts                  # external-invoker mode: ctx.tools.execute + Agent.followup
    tests/
  cli/                          # @gcszhn/mcp-sentinel-cli (harness-agnostic stdio MCP server)
    src/
      cli.ts                    # CLI entry: mcp-sentinel mcp --harness <codex|opencode|custom|none>
      mcp-server.ts             # registers the 4 tools; connection-pool mode; no notifier
      config.ts                 # codex mcp list / opencode debug config / --mcp-config discovery
    schema/                     # mcp-config.schema.json (ships in the npm tarball)
    tests/
  # future harnesses, one concrete package each:
  #   claude-code/   ...

Build order: each package builds independently, but the adapters type-check and run against @gcszhn/mcp-sentinel-core's published dist/. Run bun run build (core first, then opencode, deepseek-harness, cli) before bun test.

License

MIT