MCP Event Intelligence

MCP Event Intelligence

Durable temporal event intelligence for sleeping agents.

MCP Event Intelligence is an experimental event runtime for agents that need to react to future conditions over multiple event sources without keeping an LLM or agent loop alive.

The primary integration model is embedded and host-owned: the agent host keeps its existing MCP clients, transports, OAuth sessions and provider credentials. Event Intelligence receives a reference to the host's MCP registry, discovers the already-connected clients automatically, and uses only the Events-capable ones.

An agent can express an intent such as:

When this PR is merged, the production deploy succeeds, and no error is observed for 10 minutes, wake this task and review the release.

Event Intelligence persists the future condition independently of the model, waits for the world to satisfy it, and wakes the host only when the condition has an activation target. Conditions may also exist without an agent continuation; higher-level facts are composed separately through derived-event triggers.

Integrate with a coding agent

If you use Codex, Cursor, Copilot, Claude Code or another coding agent to add EI to an existing application, start with the [agent integration guide](docs/AI-AGENT-INTEGRATION.md) or the portable integration skill. Coding agents working on this repository should also read AGENTS.md. The LLM documentation index is a lightweight discovery aid, not an automatically installed agent plugin.

These guides use public SDK exports, keep MCP credentials and continuations host-owned, and explain how to prove durable receipt/replay behavior. The skill is stored in this GitHub repository; a consumer must explicitly make it available to their own agent environment according to that client's support.

Embed it in an existing agent host

Install from npm:

npm install mcp-event-intelligence

Opt in explicitly to the pre-v1 SDK preview (not npm latest):

npm install --save-exact mcp-event-intelligence@0.12.0-next.1

Published package: npm · Official MCP Registry

Pre-v1 upgrades: the current SDK preview is 0.12.0-next.1 (published under npm next; the npm versions page and both dist-tags were confirmed in a 2026-11-02 screenshot). See the versioned breaking-change and storage migration matrix and release notes. Plain npm install mcp-event-intelligence follows npm latest, not next; neither install command changes an already pinned host or migrates persisted data. Stable 1.0.0 has not been released.

For most runtimes, start with the runtime-neutral integration surface:

import {

createEmbeddedRuntimeIntegration, createEventSourceRegistry, } from 'mcp-event-intelligence/embedded';

const ei = await createEmbeddedRuntimeIntegration({ dataDir: './data/event-intelligence',

// The host owns transports, auth and connection lifecycle. eventSources: createEventSourceRegistry({ list: () => runtime.events.connections(), subscribe: (refresh) => runtime.events.onConnectionsChanged(refresh), }),

// EI emits an activation. The host decides what "resume" means. activation: { resolveTarget: (target) => runtime.resolveContinuation(target), hasReceipt: (receiptId) => runtime.hasWakeReceipt(receiptId), deliver: ({ activation, target, receiptId }) => runtime.resumeFromEvent({ activation, target, receiptId }), },

// Optional. Runtimes without an agent-tool surface can omit tooling entirely. tooling: { resolveContext: (ctx) => ({ target: runtime.currentContinuation(ctx), actor: runtime.currentActor(ctx), owner: runtime.currentOwner(ctx), }),

// Host-owned control. EI does not reduce authorization/approval/interrupt // semantics to a boolean. control: (request) => runtime.policy.control(request),

// Optional host-owned result projection. Large results may be externalized // behind a runtime-specific reference instead of entering model context. projectResult: (request) => runtime.results.project(request), }, });

The continuation target is intentionally opaque to EI apart from { runtime, kind, id }. A host may map it to a Turn, Execution, thread, graph checkpoint, workflow, Case, or any other durable continuation primitive.

The returned tools are neutral descriptors with EI-neutral capability metadata:

for (const tool of ei.toolCatalog.all) {

// The host translates this descriptor into its own tool/capability system. runtime.tools.register(tool); }

The embedded catalog includes source discovery plus the complete durable trigger lifecycle: trigger_create, trigger_list, trigger_inspect, trigger_pause, trigger_resume, trigger_update and trigger_delete. Trigger reads are owner-scoped through the identity returned by resolveContext(); durable mutations still pass through the host's control() boundary.

EI intentionally ships no per-runtime adapter matrix such as toOpenAI(), toAnthropic(), toMuffin() or toArtemis(). There are too many runtimes, and adding one runtime must never require changing EI core. The host consumes the same neutral contract and performs the final translation at its own boundary.

Tool exposure is also host-owned. toolCatalog.list({ capabilityIds }) can project only the capabilities the host has decided to expose. EI supplies metadata such as read vs durable mutation; it does not decide the host's RBAC, risk tiers, approval flow or interrupt UX.

For durable mutations, tooling.control() returns either:

• { action: 'execute', execution?: ... } — proceed, optionally attaching host policy/approval provenance; or
• { action: 'return', result: ... } — stop and return an opaque host-owned outcome. That outcome may mean denied, approval required, interrupted, deferred, or anything else the host runtime supports.

EI never interprets the second case. This keeps authorization, human approval and interrupt semantics entirely outside the event engine.

Result handling follows the same boundary. projectResult() may keep a small value inline or replace it with a host-owned reference. EI does not become a blob store, artifact system or model-context manager.

The package contains no named-runtime dispatch such as if (runtime === "muffin"), "artemis", "openai" or "anthropic". A new runtime should require only host-boundary code outside EI core.

The lower-level host API remains available when a runtime needs direct control:

Pass the harness-level MCP registry once — not every MCP one by one:

import {

createEventIntelligenceHost, createMcpRegistryAdapter, } from 'mcp-event-intelligence/host';

const ei = await createEventIntelligenceHost({ dataDir: './data', mcpRegistry: createMcpRegistryAdapter({ listConnections: () => host.mcp.listConnections(), subscribe: (refresh) => host.mcp.onConnectionsChanged(refresh), }), wake: async (packet, activation) => { const receipt = await host.resume(packet.target, { packet, activation, }); return { runtimeReceiptId: receipt.id }; }, });

Event Intelligence enumerates the host registry automatically. GitHub, Gmail, private/company MCPs and future connections do not need to be configured again inside EI. Tools-only MCPs remain available to the agent and are ignored by the Events layer; Events-capable MCPs are attached automatically.

Agent-first trigger flow

Agents do not need a second DSL or a model-specific planner. The public authoring path is:

event_sources_list

↓ trigger_language_describe (only when grammar discovery is useful) ↓ trigger_plan ↓ Pattern AST definition ↓ trigger_create

planTrigger() is deterministic: it resolves live event sources, fills serverId, validates subscription arguments and predicate/pattern field paths against advertised schemas, and returns the canonical trigger definition plus the required connection IDs.

For a simple condition, omitting pattern produces an allOf Pattern over the declared events:

const plan = await ei.planTrigger({

events: [{ id: 'invoice', event: 'erpnext.sales_invoice.submitted', where: [ { path: 'grand_total', op: 'gt', value: 10000 }, ], }], withinMs: 60 * 60 * 1000, target: { runtime: 'agent', kind: 'conversation', id: 'chat-42', }, continuation: { instruction: 'Check the submitted invoice for anomalies and report back in this conversation.', }, });

For advanced CEP, author the same canonical pattern directly:

const language = ei.describeTriggerLanguage({ category: 'pattern' });

const plan = await ei.planTrigger({ events: [ { id: 'order', event: 'erpnext.sales_order.created' }, { id: 'failure', event: 'payments.failed' }, { id: 'ticket', event: 'support.ticket.created' }, ], withinMs: 30 * 60 * 1000, pattern: { version: '2', partitionBy: [{ key: 'customer', fields: [ { ref: 'order', path: 'customer' }, { ref: 'failure', path: 'customer' }, { ref: 'ticket', path: 'customer' }, ], }], root: { kind: 'aggregate', function: 'sum', ref: 'order', path: 'grand_total', op: 'gte', value: 10000, child: { kind: 'sequence', contiguity: 'followedBy', children: [ { kind: 'event', ref: 'order' }, { kind: 'repeat', child: { kind: 'event', ref: 'failure' }, min: 2, max: 5, mode: 'greedy', }, { kind: 'optional', child: { kind: 'event', ref: 'ticket' }, mode: 'greedy', }, ], }, }, }, target: { runtime: 'agent', kind: 'conversation', id: 'chat-42', }, continuation: { instruction: 'Review this customer payment-risk pattern.', }, });

Pattern AST is the single canonical trigger execution model. It covers nested boolean and sequence patterns, contiguity, repeat/optional quantifiers, bounded negative patterns, calendar/absence/debounce/rate/distinct semantics, event-time windows, cross-event comparisons and arithmetic, aggregates, state transitions, partitioning, match-selection policy and deterministic derived measures.

The wire schema currently identifies this grammar as version: "2"; that is a schema version, not a second execution architecture.

The runtime is deterministic first. A first-class semantic node is available only when structural data cannot express the condition reliably. It is vendor-neutral and calls the configured SemanticEvaluator; the bundled TypeSafe Jev adapter is optional when TYPESAFE_API_KEY is present. Semantic