Agentbridge Protocol

AgentBridge

An AI-native action layer for the web.

Web apps publish a manifest of structured, permissioned actions. AI agents discover, validate, and call those actions through MCP — instead of clicking around UIs that were designed for humans.

[](https://github.com/marmar9615-cloud/agentbridge-protocol/actions/workflows/ci.yml) [](LICENSE) [](https://www.typescriptlang.org/) [](https://nextjs.org/) [](https://modelcontextprotocol.io) []() [](https://www.npmjs.com/package/@marmarlabs/agentbridge-sdk)

---

Status

AgentBridge v0.4.0 is live on npm under the @marmarlabs scope (published via npm Trusted Publishing with SLSA build provenance). The v0.4.0 line ships the opt-in Streamable HTTP MCP transport, adopter quickstart, manifest-pattern catalogue, and OpenAPI regression fixtures. See [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md) for the full release notes.

v0.5.0 (Signed manifests) is in design — design-first PR landing now, no runtime change yet. Publishers will be able to sign their /.well-known/agentbridge.json with a key set served at /.well-known/agentbridge-keys.json; agents and the MCP server will verify the manifest offline before trusting any action. Verification is additive — confirmation gate, origin pinning, target-origin allowlist, audit redaction, stdio stdout hygiene, and HTTP transport auth/origin checks all continue to enforce on top. See [docs/designs/signed-manifests.md](docs/designs/signed-manifests.md) and [docs/adr/0002-signed-manifests.md](docs/adr/0002-signed-manifests.md) for the design and decision record. Tracking issue: #31.

The v0.4.0 line shipped:

• An opt-in Streamable HTTP MCP transport with static

bearer-token auth, exact-origin allowlist, and loopback-by- default bind. stdio remains the default for local desktop clients — nothing about the existing stdio behavior changes. HTTP is opt-in via AGENTBRIDGE_TRANSPORT=http and fails closed on missing token, missing Origin allowlist for public bind, or token-in-query-string. Design: [docs/designs/http-mcp-transport-auth.md](docs/designs/http-mcp-transport-auth.md); ADR: [docs/adr/0001-http-mcp-transport.md](docs/adr/0001-http-mcp-transport.md).

• An adopter quickstart ([docs/adopter-quickstart.md](docs/adopter-quickstart.md))

and manifest-pattern catalogue ([docs/manifest-patterns.md](docs/manifest-patterns.md)) for existing-app onboarding.

• OpenAPI converter regression fixtures

([examples/openapi-regression](examples/openapi-regression)) pinning stable mapping behavior.

No published v0.x release alone is v1.0 production readiness; each is a step toward it. The HTTP transport is experimental in v0.4.0.

npm install @marmarlabs/agentbridge-sdk @marmarlabs/agentbridge-core
npx @marmarlabs/agentbridge-cli scan http://localhost:3000
npx @marmarlabs/agentbridge-mcp-server

AgentBridge is usable today for local development, app prototyping, manifest authoring, scanner workflows, OpenAPI import, and MCP experiments. It is not yet production security infrastructure — signed manifests (v0.5.0, in design), OAuth scope enforcement, and distributed audit storage are roadmap items (see [docs/roadmap.md](docs/roadmap.md)). Destructive demo actions remain simulated.

For release notes, see [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md) for the latest shipped release, [docs/releases/v0.3.0.md](docs/releases/v0.3.0.md) for the production-foundations release, [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md) for the Codex onboarding release, [docs/releases/v0.2.1.md](docs/releases/v0.2.1.md) for the docs cleanup patch, and [docs/releases/v0.2.0.md](docs/releases/v0.2.0.md) for the first public release.

---

Table of contents

• [Why agent-native interfaces matter](#why-agent-native-interfaces-matter)
• [What is AgentBridge?](#what-is-agentbridge)
• [How it works](#how-it-works)
• [Architecture](#architecture)
• [The confirmation flow](#the-confirmation-flow)
• [Quick start](#quick-start)
• [Project layout](#project-layout)
• [Packages and apps](#packages-and-apps)
• [The CLI](#the-cli)
• [OpenAPI import](#openapi-import)
• [Manifest spec](#manifest-spec)
• [Demo walkthrough](#demo-walkthrough)
• [Wire it to an MCP client](#wire-it-to-an-mcp-client)
• [Manifest schema reference](#manifest-schema-reference)
• [MCP tools reference](#mcp-tools-reference)
• [Security model](#security-model)
• [Testing](#testing)
• [Documentation](#documentation)
• [Roadmap](#roadmap)
• [Contributing](#contributing)
• [License](#license)

---

Why agent-native interfaces matter

Today's web is built around the assumption that a human will be there — clicking, scrolling, reading visual hierarchy, dismissing modals, recovering from confusing error states. When an AI agent has to operate that same surface, it ends up driving a browser blindly:

• Inferring intent from button labels and DOM structure
• Guessing at element selectors that change between deploys
• Hoping confirmation dialogs don't appear unexpectedly
• Praying that nothing visual changes mid-flow

The result is brittle, slow, and unsafe. There's no reliable way for an agent — or its operator — to reason about what an action will do before it happens.

> ### The thesis > Apps shouldn't force agents to operate a UI built for human eyes. Apps should publish what they actually do — semantically, with types, with risk metadata, with clear confirmation requirements — so agents can reason about actions before invoking them.

---

What is AgentBridge?

AgentBridge is a manifest format + SDK + MCP server that lets any web app expose its operations to AI agents safely.

The core unit is a manifest served at a well-known URL:

https://your-app.com/.well-known/agentbridge.json

The manifest declares every action the app supports, with:

| Field | Purpose | |---|---| | name, title, description | Semantic identity an agent can reason about | | inputSchema (JSON Schema) | Validate inputs before invocation | | outputSchema (JSON Schema) | Tell agents what to expect back | | risk: low \| medium \| high | Triage which actions need human-in-the-loop | | requiresConfirmation: bool | Force an explicit approval step | | humanReadableSummaryTemplate | Generate natural-language confirmation prompts | | permissions[] | Document required scopes | | examples[] | Teach agents the correct call shape |

An MCP server bridges any AgentBridge-enabled site to MCP-speaking agents (OpenAI Codex, Claude Desktop, Cursor, custom MCP clients) with enforcement built in: risky actions never execute without explicit confirmationApproved: true, every call is audited, and outbound requests are pinned to the manifest's origin.

---

How it works

flowchart LR
    A["🧑 Human user"] --> B["Web app UIorders.acme.com"]
    C["🤖 AI agent"] --> D["MCP clientCodex / Claude Desktop / Cursor / custom"]
    D  E["AgentBridgeMCP server"]
    E -->|fetch manifest| F["/.well-known/agentbridge.json"]
    E -->|invoke action| G["/api/agentbridge/actions/:name"]
    F --> B
    G --> B
    E --> H[("Audit log")]

    style A fill:#dbeafe,stroke:#2563eb
    style C fill:#fee2e2,stroke:#dc2626
    style E fill:#fef3c7,stroke:#d97706
    style H fill:#f3f4f6,stroke:#6b7280

The same web app serves two audiences:

• Humans see the visual UI, click around, and get rich layout
• Agents see the manifest, validate inputs, and invoke structured actions

Both flows share the same backend logic. Both write to the same audit log. The only difference is whether the caller is a browser or a programmatic agent.

---

Architecture

flowchart TB
    subgraph workspace["agentbridge/ (npm workspace)"]
        direction TB

        subgraph packages["packages/"]
            CORE["📦 agentbridge-coreschemas, types,validation, audit"]
            SDK["📦 agentbridge-sdkdefineAgentAction,manifest builder"]
            SCAN["📦 agentbridge-scannerreadiness scoring,structured checks"]
            OAPI["📦 agentbridge-openapiOpenAPI 3.x →manifest converter"]
            CLI["📦 agentbridge-cliscan, validate, init,generate, mcp-config"]
        end

        subgraph apps["apps/"]
            DEMO["🛒 demo-app  (:3000)Fake order management.Serves manifest + actions."]
            STUDIO["🎛 studio  (:3001)Developer dashboard.Scan, exercise, audit."]
            MCP["🔌 mcp-server  (stdio)Tools, resources, prompts.Confirmation tokens + idempotency."]
        end

        DATA[("📁 data/audit · confirmations · idempotency")]
    end

    SDK --> CORE
    SCAN --> CORE
    OAPI --> CORE
    CLI --> CORE
    CLI --> SCAN
    CLI --> OAPI
    DEMO --> SDK
    DEMO --> CORE
    STUDIO --> SCAN
    STUDIO --> CORE
    MCP --> SCAN
    MCP --> CORE

    DEMO -.writes.-> DATA
    STUDIO -.writes.-> DATA
    MCP -.writes.-> DATA
    STUDIO -.reads.-> DATA
    DEMO -.reads.-> DATA

    style CORE fill:#dbeafe,stroke:#2563eb
    style SDK fill:#dbeafe,stroke:#2563eb
    style SCAN fill:#dbeafe,stroke:#2563eb
    style OAPI fill:#dbeafe,stroke:#2563eb
    style CLI fill:#dbeafe,stroke:#2563eb
    style DEMO fill:#dcfce7,stroke:#16a34a
    style STUDIO fill:#dcfce7,stroke:#16a34a
    style MCP fill:#fef3c7,stroke:#d97706
    style DATA fill:#f3f4f6,stroke:#6b7280

---

The confirmation flow

This is the heart of the safety story. Risky actions never execute on a single agent call — they require a deliberate, two-step approval.

sequenceDiagram
    autonumber
    participant Agent as 🤖 Agent
    participant MCP as MCP Server
    participant App as Web App
    participant Audit as Audit Log

    Agent->>MCP: call_action(execute_refund_order, input)
    MCP->>App: GET /.well-known/agentbridge.json
    App-->>MCP: manifest (action.risk = "high")
    MCP->>MCP: validate input vs JSON Schema
    Note over MCP: risk=high & no confirmationApproved
    MCP->>Audit: status: confirmation_required
    MCP-->>Agent: { status: "confirmationRequired",summary: "EXECUTE refund draft xyz",hint: "re-call with confirmationApproved: true" }

    Note over Agent: Agent presents thesummary to a human

    Agent->>MCP: call_action(..., confirmationApproved: true)
    MCP->>MCP: re-validate, re-fetch manifest
    Note over MCP: confirmation cleared ✓
    MCP->>App: POST /api/agentbridge/actions/execute_refund_order
    App-->>MCP: { simulated: true, simulatedTransactionId: "..." }
    MCP->>Audit: status: completed, confirmationApproved: true
    MCP-->>Agent: { status: "ok", result: { ... } }

The Studio dashboard enforces the same gate visually — the operator must type CONFIRM in a modal before any medium- or high-risk action runs.

---

Quick start

git clone https://github.com/marmar9615-cloud/agentbridge-protocol.git
cd agentbridge-protocol

npm install      # pulls Next.js, MCP SDK, Zod, etc.
npm test         # all suites should pass
npm run dev      # demo on :3000, Studio on :3001

Then open:

• Demo app: http://localhost:3000 (the human surface)
• Manifest: http://localhost:3000/.well-known/agentbridge.json
• Studio: http://localhost:3001 (the dev dashboard)

To run the MCP server (stdio) for an MCP client:

npm run dev:mcp

Requirements: Node 20+, npm 10+. CI runs on Node 20.x and 22.x.

---

Project layout

agentbridge-protocol/
├── packages/
│   ├── core/             # 📦 schemas, types, validation, audit
│   ├── sdk/              # 📦 defineAgentAction, manifest builder
│   ├── scanner/          # 📦 readiness scoring + structured checks
│   ├── openapi/          # 📦 OpenAPI 3.x → AgentBridge manifest converter
│   └── cli/              # 📦 @marmarlabs/agentbridge-cli — scan, validate, init, generate
├── apps/
│   ├── demo-app/         # 🛒 Next.js order-management demo (port 3000)
│   ├── studio/           # 🎛 Next.js dashboard (port 3001)
│   └── mcp-server/       # 🔌 stdio MCP server: tools + resources + prompts
├── spec/
│   ├── agentbridge-manifest.schema.json   # JSON Schema for the manifest
│   ├── agentbridge-manifest.v0.1.md       # human-readable spec
│   └── examples/                          # 3 example manifests
├── examples/             # nextjs-basic · openapi-store · mcp-client-config · codex-config · codex-plugin
├── docs/                 # quickstart, mcp-client-setup, codex-setup, openapi-import, roadmap
├── data/                 # 📁 local audit/confirmations/idempotency (gitignored)
├── .github/workflows/    # CI
├── AGENTS.md             # model-neutral working notes for AI coding agents
├── CLAUDE.md             # deeper Claude-Code-specific working notes
├── CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md / CHANGELOG.md
├── README.md
└── LICENSE               # Apache 2.0

---

Packages and apps

📦 packages/core

The shared contract. Everything depends on this.

import {
  AgentBridgeManifestSchema,
  validateManifest,
  isRiskyAction,
  summarizeAction,
  createAuditEvent,
  appendAuditEvent,
} from "@marmarlabs/agentbridge-core";

const result = validateManifest(rawJson);
if (result.ok) {
  for (const action of result.manifest.actions) {
    if (isRiskyAction(action)) {
      console.log("Needs confirmation:", action.name);
    }
  }
}

Key exports:

• Zod schemas for the manifest, actions, resources, permissions, audit events
• validateManifest(json) — { ok, manifest } or { ok: false, errors[] }
• isRiskyAction(action) — boolean confirmation gate
• summarizeAction(action, input) — fills humanReadableSummaryTemplate with {{key}} placeholders
• createAuditEvent, appendAuditEvent, readAuditEvents — JSON-file audit log with PII redaction (strips authorization, cookie, password, token, secret recursively)

📦 packages/sdk

The author's interface. Define actions ergonomically with Zod, get JSON Schema for free.

import { defineAgentAction, createAgentBridgeManifest, z } from "@marmarlabs/agentbridge-sdk";

const refundAction = defineAgentAction({
  name: "draft_refund_order",
  title: "Draft a refund",
  description: "Creates a refund draft. Not executed until confirmed via execute_refund_order.",
  method: "POST",
  endpoint: "/api/agentbridge/actions/draft_refund_order",
  risk: "medium",
  requiresConfirmation: true,
  inputSchema: z.object({
    orderId: z.string().min(1),
    reason: z.string().min(3),
    amount: z.number().positive(),
  }),
  outputSchema: z.object({
    draftId: z.string(),
    summary: z.string(),
  }),
  humanReadableSummaryTemplate:
    "Draft a refund of ${{amount}} on order {{orderId}} (reason: {{reason}})",
  examples: [
    {
      description: "Partial refund for a damaged item",
      input: { orderId: "ORD-1001", reason: "Damaged on arrival", amount: 24 },
    },
  ],
});

export const manifest = createAgentBridgeManifest({
  name: "Acme Order Manager",
  version: "1.0.0",
  baseUrl: "https://acme.com",
  contact: "platform@acme.com",
  actions: [refundAction /* ... */],
});

The SDK converts Zod → JSON Schema (via zod-to-json-schema) automatically, so you get one source of truth for both runtime validation and the published manifest.

📦 packages/scanner

Audit any URL for agent readiness. Returns a 0–100 score plus actionable recommendations.

import { scanUrl } from "@marmarlabs/agentbridge-scanner";

const report = await scanUrl("http://localhost:3000");
// {
//   score: 100,
//   manifestFound: true,
//   validManifest: true,
//   actionCount: 5,
//   riskyActionCount: 3,
//   missingConfirmationCount: 0,
//   issues: [],
//   recommendations: [],
// }

Scoring rubric:

| Issue | Deduction | |---|---:| | No manifest at all | → score 0 | | Manifest invalid against schema | → score 10 | | No actions declared | −30 | | Missing contact field | −5 | |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marmar9615-cloud
• Source: marmar9615-cloud/agentbridge-protocol
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.