App Context MCP broker

This package is the local MCP broker for App Context applications. An agent host configures one stdio server; the broker discovers running application instances and projects their semantic actions and state through standard MCP tools and resources.

The architecture is established by ADR-001 and the draft App Context MCP Profile 0.1. Version 0.1.2 is a public alpha; pin it in an MCP host so the broker does not change unexpectedly across restarts.

Run

npx --yes @appcontextprotocol/[email protected]

For broker development, run the equivalent command from a source checkout:

pnpm install
pnpm build
node /absolute/path/to/appcontextprotocol/packages/mcp-bridge/dist/bin.js

Register either command as a local stdio MCP server in the host you want to test. The broker writes protocol messages only to standard output; diagnostics and application logs must use standard error.

Stable compatibility tools

The broker always advertises four tools so hosts that cache their initial tool list can still use applications launched later:

• apps_list lists live application instances and their opaque instanceId values.
• app_describe returns one exact instance's semantic surface.
• app_state reads all state or selected keys from one exact instance.
• app_call calls an action by exact name on one exact instance.

app_describe, app_state, and app_call require the opaque instanceId returned by apps_list. Their results repeat appId and instanceId, so a caller can verify which launch answered instead of silently following a replacement process.

The old acp_list_apps and acp_get_state names remain callable during migration, but they are not advertised and are not part of the public contract.

Dynamic typed tools

Every compatible action is also projected as a typed MCP tool. Names are deterministic, capped at 128 characters, scoped to the launch, and include a digest of the action registration and its advertised surface. Re-registering an action therefore invalidates a cached handle—even when its description and schema stay the same—instead of redirecting it to a new handler. Each tool retains the application's input JSON Schema, including its explicit dialect, and carries MCP annotations plus App Context metadata.

The direct application endpoint and broker preserve explicit readOnlyHint, destructiveHint, idempotentHint, and openWorldHint values. New App Context endpoints always state destructiveness as true or false. When an older or third-party endpoint omits both read-only and destructiveness metadata, the broker treats the action as destructive rather than making an unsafe guess.

Typed tools are progressive enhancement: the broker advertises tools.listChanged and sends notifications/tools/list_changed, but the stable tools remain the fallback for MCP hosts that do not refresh dynamically.

Confirmation is not an MCP annotation. A confirmation-required action is labeled for the client, while the application remains responsible for enforcing the decision and making its best-effort audit attempt.

Resources and subscriptions

State is exposed as JSON resources scoped to a specific launch:

appcontext://apps/<appId>/<instanceId>/state
appcontext://apps/<appId>/<instanceId>/state/<key>

Clients can list, read, subscribe, and unsubscribe. An application state change becomes notifications/resources/updated, which tells the client to read the current value again. Application and surface changes become resource-list and tool-list change notifications.

Transient events are deliberately not rebranded as arbitrary MCP notifications. In profile 0.1 they are projected into a bounded, sequenced journal resource:

appcontext://apps/<appId>/<instanceId>/events

The journal contains only events observed while the MCP resource is subscribed and is not a durable event bus.

Current compatibility boundary

The broker uses the direct MCP endpoint whenever an application advertises one and fails closed if that endpoint cannot be validated or reached; it never silently downgrades that launch. Only old manifests with no MCP advertisement may use the original local WebSocket client as a package-private compatibility channel. Agent hosts see MCP only; the compatibility hop is not a second public agent protocol.

Alpha limits

Direct connection with an unmodified MCP SDK client, delayed startup/restart, same-app instances, narrow independent-host calls, controlled layer measurements, profile conformance, and clean registry installation pass. Version 0.1 still uses a same-user local trust boundary; per-agent authorization, audit redaction and attribution, cancellation, downstream pagination/load tests, and the final MCP 2026 migration remain future hardening work.