# Agentbridge Protocol

> An AI-native action layer that helps apps expose structured, permissioned actions for agents through manifests, MCP tools, confirmations, and audit logs.

- **Type:** MCP server
- **Install:** `agentstack add mcp-marmar9615-cloud-agentbridge-protocol`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [marmar9615-cloud](https://agentstack.voostack.com/s/marmar9615-cloud)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [marmar9615-cloud](https://github.com/marmar9615-cloud)
- **Source:** https://github.com/marmar9615-cloud/agentbridge-protocol

## Install

```sh
agentstack add mcp-marmar9615-cloud-agentbridge-protocol
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/marmar9615-cloud/agentbridge-protocol/issues/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.

```bash
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

```mermaid
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

```mermaid
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.

```mermaid
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

```bash
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:

```bash
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.

```typescript
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.

```typescript
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.

```typescript
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](https://github.com/marmar9615-cloud)
- **Source:** [marmar9615-cloud/agentbridge-protocol](https://github.com/marmar9615-cloud/agentbridge-protocol)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-marmar9615-cloud-agentbridge-protocol
- Seller: https://agentstack.voostack.com/s/marmar9615-cloud
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.