v0.4.0 — HTTP MCP Transport + Auth

v0.4.0 — HTTP MCP Transport + Auth

Status. ✅ Released. All six @marmarlabs/agentbridge-*
packages are live on npm at 0.4.0, published via GitHub
Actions Trusted Publishing (OIDC) with SLSA build provenance
attestations. Tag
v0.4.0
points at the release commit
2e745163f09842f2af5ebc94e14b725708759e94.

1. Summary

v0.4.0 adds an opt-in Streamable HTTP MCP transport with a
static bearer-token auth model, exact-origin allowlist, and
loopback-by-default bind. The default and only-when-unset
transport remains stdio; nothing about the existing stdio
behavior changes. Existing v0.3.0 install commands keep working
unchanged.

The release also incorporates v0.4.0-line OpenAPI converter
regression fixtures (PR #26) and the v0.4.0-line adopter docs +
manifest patterns shipped in v0.3.x maintenance work (PR #25),
giving the line a coherent docs/examples baseline before the next
implementation cycle.

2. What changed

Area	Change
MCP transport	New opt-in HTTP transport. stdio remains the default.
MCP server	createMcpServer() factory introduced (PR #24); both transports share it.
Config	New env vars: AGENTBRIDGE_TRANSPORT, AGENTBRIDGE_HTTP_HOST, AGENTBRIDGE_HTTP_PORT, AGENTBRIDGE_HTTP_AUTH_TOKEN, AGENTBRIDGE_HTTP_ALLOWED_ORIGINS.
Safety	Public bind fails closed without auth + Origin allowlist. Bearer token never logged. Tokens in URL query strings rejected with 400. Constant-time bearer compare.
OpenAPI	Added regression fixtures + tests (examples/openapi-regression/, packages/openapi/src/tests/openapi-fixtures.test.ts) covering action-name normalization, method-risk inference, request/response schema conversion, skipped methods, metadata inheritance.
Docs	New design doc, ADR, security configuration recipes, mcp-client-setup HTTP section, adopter quickstart, manifest patterns.
CLI	agentbridge mcp-config now prints an opt-in HTTP transport block alongside the stdio snippets.
Examples	New examples/http-client-config/ recipe + curl smoke.
Smoke	New scripts/http-mcp-smoke.mjs + npm run smoke:http. Wired into the local pre-publish smoke flow.

Versions bumped in lockstep: every workspace package goes from
0.3.0 → 0.4.0. SERVER_VERSION in
apps/mcp-server/src/server.ts
also moves to 0.4.0 so serverInfo.version reflects the
release.

3. New HTTP transport

The HTTP transport wraps StreamableHTTPServerTransport from
@modelcontextprotocol/sdk behind:

• Bearer-token auth. Authorization: Bearer <token> only.
  Tokens are compared in constant time (crypto.timingSafeEqual
  with length padding). Tokens in URL query strings (?token=,
  ?access_token=, ?bearer=, ?auth=, ?authorization=) are
  rejected with HTTP 400 before any tool runs.
• Origin validation. Inbound Origin headers must exactly
  match an entry in AGENTBRIDGE_HTTP_ALLOWED_ORIGINS (compared
  via URL.origin; no prefix matching, no wildcard). Non-browser
  CLI clients with no Origin header are allowed if the bearer
  token is valid.
• Loopback-by-default bind. Default host is 127.0.0.1,
  default port 3333. Public bind (0.0.0.0 or any
  non-loopback host) is allowed but requires both
  AGENTBRIDGE_HTTP_AUTH_TOKEN and a non-empty
  AGENTBRIDGE_HTTP_ALLOWED_ORIGINS — otherwise the server fails
  closed at startup with a clear stderr message.
• JSON responses, stateless mode. No SSE in v0.4.0. No
  session IDs.
• Endpoint: POST /mcp. OPTIONS /mcp handles CORS preflight
  for allowed origins. Any other path returns 404.
• Body cap. Reuses AGENTBRIDGE_MAX_RESPONSE_BYTES as the
  inbound request-body limit (default 1 MB).

The dispatcher, every safety check, the confirmation gate, the
target-origin allowlist, idempotency, and audit redaction are all
shared with stdio. Auth and Origin checks sit in front of
transport.handleRequest(), never inside the dispatcher.

4. Security posture

Property	Status	Where it lives
stdio default unchanged	✅ enforced	apps/mcp-server/src/index.ts (resolveTransport() defaults stdio)
HTTP requires auth	✅ enforced at startup	apps/mcp-server/src/transports/http.ts:validateHttpStartup
Public bind requires auth + origins	✅ enforced at startup	same
Tokens in query strings	🚫 rejected with 400	transports/http.ts request handler
Token never logged	✅ verified by tests	http-transport.test.ts
Constant-time bearer compare	✅ crypto.timingSafeEqual	transports/http.ts:verifyBearer
Exact-origin Origin match	✅ URL.origin, no wildcard	transports/http.ts:isOriginAllowed
CORS never wildcard with credentials	✅ echoes exact origin	transports/http.ts:writeAllowedOriginCorsHeaders
Loopback-by-default bind	✅ default 127.0.0.1	apps/mcp-server/src/config.ts:DEFAULTS.HTTP_HOST
Stdout hygiene preserved	✅ verified by stdio-hygiene.test.ts	apps/mcp-server/src/tests/stdio-hygiene.test.ts
Confirmation gate unchanged	✅ still single-use, input-bound, TTL-bounded	apps/mcp-server/src/confirmations.ts
Origin pinning unchanged	✅ outbound assertSameOrigin enforced before every action call	apps/mcp-server/src/safety.ts
Audit redaction unchanged	✅ redact strips secret-shaped keys recursively	packages/core/src/audit.ts
Demo destructive actions still simulated	✅ no real payment processor wired	apps/demo-app/lib/actions.ts

Threat model T14 ("Future HTTP transport risks") moves from
designed to implemented; remaining gaps are documented in
docs/threat-model.md.

5. New env vars

Universal:

• AGENTBRIDGE_TRANSPORT — stdio (default) | http. Unknown
  values fall back to stdio with a stderr warning.

HTTP-mode only (no effect under stdio):

• AGENTBRIDGE_HTTP_HOST — default 127.0.0.1. Anything other
  than loopback is "public bind" with stricter validation.
• AGENTBRIDGE_HTTP_PORT — default 3333. 0 selects an
  ephemeral port (used by tests). Range 0–65535; out-of-range
  values are clamped with a stderr warning.
• AGENTBRIDGE_HTTP_AUTH_TOKEN — required for HTTP mode.
  Static bearer token; ≥ 16 chars. Generate with
  openssl rand -hex 32. Never logged, never echoed, never
  thrown in error messages.
• AGENTBRIDGE_HTTP_ALLOWED_ORIGINS — comma-separated inbound
  Origin allowlist; required for non-loopback bind. Independent
  from the outbound AGENTBRIDGE_ALLOWED_TARGET_ORIGINS.

Existing v0.3.0 env vars (AGENTBRIDGE_ALLOWED_TARGET_ORIGINS,
AGENTBRIDGE_ALLOW_REMOTE, AGENTBRIDGE_ACTION_TIMEOUT_MS,
AGENTBRIDGE_MAX_RESPONSE_BYTES, AGENTBRIDGE_CONFIRMATION_TTL_SECONDS,
AGENTBRIDGE_DATA_DIR) apply to both transports identically.

Full table:
docs/security-configuration.md.

6. Stdio compatibility

• No env var change is required for existing stdio installs.
• npx -y @marmarlabs/agentbridge-mcp-server continues to launch
  the stdio MCP server.
• serverInfo returned by initialize now reads
  { name: "agentbridge", version: "0.4.0" }. Tool list,
  resources list, prompts list, and call shapes are byte-identical
  to v0.3.0.
• Stdout still carries only JSON-RPC bytes; diagnostics and
  warnings still go to stderr.
• stdio-hygiene.test.ts continues to pass against the built
  v0.4.0 dist binary.

7. Codex / Claude Desktop / generic MCP client notes

For local desktop clients, stdio remains the recommended
default. Existing snippets in
docs/codex-setup.md and
docs/mcp-client-setup.md keep working
unchanged.

For hosted/centralized MCP clients that cannot launch a local
subprocess, the new HTTP transport is now available. See
examples/http-client-config/
for a working local-dev recipe and curl-based smoke checks.
docs/mcp-client-setup.md gained an
"HTTP MCP transport (experimental, v0.4.0)" section.

8. OpenAPI converter regression fixtures (PR #26)

examples/openapi-regression/
ships a richer regression fixture and
packages/openapi/src/tests/openapi-fixtures.test.ts
covers stable mapping behavior — action-name normalization,
method-risk inference, request/response schema conversion,
skipped methods, metadata inheritance, and current
unsupported-security/example mapping behavior.

9. Adopter quickstart and manifest patterns (PR #25)

docs/adopter-quickstart.md is a
practical existing-app onboarding guide. It walks through adding
manifests, action endpoints, CLI validation, scanner checks, MCP
client setup, and production safety review.

docs/manifest-patterns.md collects
reusable patterns for read actions, draft actions,
confirmation-required mutations, idempotent calls, resources, and
auth/contact metadata.

10. Migration notes from v0.3.0

• No code changes required for stdio adopters. Run
  npm install @marmarlabs/agentbridge-* @0.4.0 (or the version
  range that suits your project) once v0.4.0 is on npm.
• For HTTP adopters (new): generate an auth token, set
  AGENTBRIDGE_TRANSPORT=http and the matching
  AGENTBRIDGE_HTTP_* env vars, and follow the recipe in
  examples/http-client-config/README.md.
• No manifest schema changes. Existing manifests served at
  /.well-known/agentbridge.json keep working unchanged.
• No CLI command removals. agentbridge scan / validate /
  init / generate openapi / mcp-config keep their existing
  command surface; mcp-config now prints an additional HTTP
  exa...

v0.3.0 — Production Foundations

v0.3.0 — Production Foundations

Date: 2026-04-28
Status: Published. All six packages live on npm at 0.3.0,
published via the new release-publish.yml workflow using npm
Trusted Publishing (OIDC) with build provenance attached.
Tagged as v0.3.0 and released on GitHub.

This release is the foundation step on the path to a stable
production AgentBridge v1.0.0. It does not declare
production-readiness — it builds the docs, threat model, allowlist
behavior, and supply-chain plan that v1.0 will depend on. The full
checklist of what v1.0 actually needs is in
docs/v1-readiness.md.

Highlights

• Stricter remote-target allowlist.
  AGENTBRIDGE_ALLOWED_TARGET_ORIGINS is the new
  production-recommended way to permit non-loopback target hosts.
  Exact URL.origin match. Loopback stays allowed by default.
  AGENTBRIDGE_ALLOW_REMOTE=true still works for testing and now
  emits a one-time stderr warning. The strict allowlist always wins.
• Configurable bounds. Three new env vars (AGENTBRIDGE_ACTION_TIMEOUT_MS,
  AGENTBRIDGE_MAX_RESPONSE_BYTES, AGENTBRIDGE_CONFIRMATION_TTL_SECONDS)
  are clamped to safe ranges and warn on out-of-range / non-integer
  input. Defaults are unchanged from v0.2.2.
• Stdout hygiene test. A new subprocess test boots the built
  MCP server and asserts every stdout line is parseable JSON-RPC
  and that warnings are routed to stderr only.
• Threat model published. docs/threat-model.md
  catalogues 15 threats with current mitigations, gaps, v1.0 targets,
  and test pointers.
• v1.0 readiness checklist published. docs/v1-readiness.md
  pins down what we mean by "production-ready" and what's left.
• Production-readiness guide published. docs/production-readiness.md
  draws the line between today's safe-for-local and tomorrow's
  safe-for-financial-actions, with a pre-flight checklist.
• Security configuration reference published. docs/security-configuration.md
  is the authoritative env-var table, with bounds, recipes, and
  examples for every supported MCP client.
• npm Trusted Publishing workflow shipped and exercised.
  .github/workflows/release-publish.yml
  is workflow_dispatch-only, defaults to dry_run=true, and uses
  OIDC instead of a long-lived NPM_TOKEN. Used to publish v0.3.0
  end-to-end with provenance — see
  docs/trusted-publishing.md.

What you can use today

After upgrading to v0.3.0, the following paths become available:

# Production-recommended: strict origin allowlist, persistent data dir,
# tightened TTL.
export AGENTBRIDGE_ALLOWED_TARGET_ORIGINS=https://staging.app.internal
export AGENTBRIDGE_DATA_DIR=/var/lib/agentbridge/staging
export AGENTBRIDGE_CONFIRMATION_TTL_SECONDS=120
npx -y @marmarlabs/agentbridge-mcp-server

# Local dev (unchanged from v0.2.2)
npx -y @marmarlabs/agentbridge-mcp-server

The agentbridge mcp-config CLI prints these snippets out of the
box and now points at the new docs.

What changed for the safety story

Nothing weakened. Specifically:

• The confirmation gate still refuses every risky action without
  confirmationApproved: true AND a single-use, input-bound
  confirmationToken.
• Origin pinning still rejects any action endpoint whose
  URL.origin differs from the manifest's baseUrl.
• Audit redaction still strips authorization, cookie,
  password, token, secret, api_key, apikey recursively
  before persisting.
• The demo app's destructive actions are still simulated.
• Loopback is still the default. Two opt-ins (strict allowlist;
  broad escape hatch with stderr warning) are documented.

What's NOT in v0.3.0

• HTTP MCP transport — planned for v0.4.0.
• OAuth / authorization — planned for v0.4.0.
• Signed manifests — planned for v0.5.0.
• Pluggable persistent storage — planned for v0.7.0.
• Policy engine integration — planned for v0.6.0.
• Any new manifest spec changes — schema is stable for v0.x.

Supply-chain status

• v0.2.0 / v0.2.1 / v0.2.2 were published manually with temporary
  granular tokens that were revoked after each publish.
• v0.3.0 was published via npm Trusted Publishing (OIDC) from
  GitHub Actions — no NPM_TOKEN secret was used, no long-lived
  publish credentials existed at any point.
• Every v0.3.0 tarball carries an SLSA build provenance
  attestation
  recorded at https://registry.npmjs.org/-/npm/v1/attestations/<pkg>@0.3.0.
  Verifiable on each package's npmjs.com page (look for the green
  "Provenance" check) and via npm view <pkg>@0.3.0 dist.attestations.
• The Trusted Publisher records on npm point at
  marmar9615-cloud/agentbridge-protocol →
  .github/workflows/release-publish.yml, with no environment
  scope (so any main-based dispatch can publish).

Tests

• Existing 87 tests still pass.
• New test files:
  • apps/mcp-server/src/tests/safety.test.ts
    — 20 cases covering loopback default, AGENTBRIDGE_ALLOW_REMOTE
    warning, exact-origin allowlist, prefix attacks, port mismatch,
    non-http schemes, multi-origin, and allowlist-wins-over-broad
    interaction.
  • apps/mcp-server/src/tests/config.test.ts
    — 11 cases covering the three configurable bounds: defaults,
    in-range values, clamp behavior on too-low / too-high, and
    fallback on non-integer input.
  • apps/mcp-server/src/tests/stdio-hygiene.test.ts
    — 3 cases covering clean shutdown, JSON-RPC parseability, and
    stderr-routing of the broad-remote warning. Builds the dist
    on demand in beforeAll.

How to evaluate v0.3.0 from a clean checkout

git clone https://github.com/marmar9615-cloud/agentbridge-protocol.git
cd agentbridge-protocol
git checkout v0.3.0
npm ci
npm run typecheck:clean
npm test
npm run build
npm run pack:dry-run
npm run smoke:external
node packages/cli/dist/bin.js version       # 0.3.0
node packages/cli/dist/bin.js mcp-config    # mentions AGENTBRIDGE_ALLOWED_TARGET_ORIGINS

The same gate is documented in
docs/release-checklist.md for the next
release.

See also

• docs/v1-readiness.md
• docs/production-readiness.md
• docs/threat-model.md
• docs/security-configuration.md
• docs/trusted-publishing.md
• CHANGELOG.md

v0.2.2 — OpenAI Codex Onboarding

v0.2.2 — OpenAI Codex onboarding

Date: 2026-04-27
Status: Stable, additive release on top of v0.2.1. Same protocol,
same code, same safety story — better onboarding for OpenAI Codex
users, plus client-neutral docs.

AgentBridge already worked with OpenAI Codex at the protocol level
because the bundled MCP server speaks stdio and Codex can launch
any stdio MCP server. This release closes the onboarding gap: a
dedicated Codex setup doc, copy-pasteable config.toml snippets, an
AGENTS.md for any AI coding agent looking at the
repo, an experimental local plugin skeleton, and an updated mcp-config
CLI command that emits Codex configs alongside the existing ones.

Headline changes

• Codex setup is one command. codex mcp add agentbridge -- npx -y @marmarlabs/agentbridge-mcp-server registers the AgentBridge server
  in Codex.
• config.toml blocks for global and project-scoped Codex. Drop
  the same six lines into ~/.codex/config.toml (every Codex session)
  or .codex/config.toml (one repo only).
• agentbridge mcp-config is now multi-client. The CLI prints
  Codex CLI / Codex config.toml / Claude Desktop / Cursor / raw
  stdio snippets in one go.
• AGENTS.md lands at the repo root — short, model-neutral, sits
  next to the deeper Claude-focused CLAUDE.md for any agent reading
  the code.
• No behavior change. Same MCP tools, same confirmation tokens,
  same origin pinning, same loopback-only default, same audit
  redaction, same simulated destructive demo actions.

What's new

Documentation

• docs/codex-setup.md — full walkthrough:
  three setup options (CLI, global config, project-scoped),
  demo-app pairing, prompt suggestions, troubleshooting, safety
  reminders, links into the rest of the docs.
• docs/mcp-client-setup.md —
  restructured to be client-neutral with sections for OpenAI Codex,
  Claude Desktop, Cursor, and custom clients, plus a "Safety
  expectations for all clients" block that names the invariants
  enforced regardless of which client is talking to the server.
• AGENTS.md — model-neutral working notes
  (project summary, layout, core commands, safety invariants, release
  rules, how-to-add-a-new-MCP-client). Sibling to
  CLAUDE.md, which stays as the deeper
  Claude-Code-specific reference.
• Root README.md gained a "Works with MCP
  clients" subsection in the wiring section, a Codex one-liner, a
  Cursor JSON snippet, and an AGENTS.md row in the docs table.

Examples

• examples/codex-config/ —
  copy-pasteable config.global.toml, config.project.toml, and a
  README that explains when to use which.
• examples/codex-plugin/ —
  experimental local Codex plugin skeleton:
  .codex-plugin/plugin.json, .mcp.json, and
  skills/agentbridge/SKILL.md. Not a published plugin — treat
  it as illustrative; the supported flow is docs/codex-setup.md.
• examples/mcp-client-config/
  README gained a Codex section and standardized JSON snippets on
  npx -y so first-run installs don't prompt.

CLI

• agentbridge mcp-config now prints, in this order:
  • raw stdio command (any MCP-compatible client)
  • OpenAI Codex CLI one-liner (codex mcp add agentbridge ...)
  • OpenAI Codex ~/.codex/config.toml block
  • Claude Desktop JSON
  • Cursor / generic MCP JSON
  • Local checkout (node ./apps/mcp-server/dist/index.js)
  • Safety reminder (loopback default + confirmation token reminder)
• New CLI test
  (packages/cli/src/tests/cli.test.ts)
  asserts each block is present in the output.

Per-package READMEs

The @marmarlabs/agentbridge-mcp-server and
@marmarlabs/agentbridge-cli READMEs got new Codex setup sections.
The other four publishable READMEs (core, sdk, scanner,
openapi) updated their Status blocks to describe v0.2.2 as the
Codex-onboarding release for consistency.

What did not change

• No protocol behavior, schema, or build-output changes.
• No safety invariant changes — confirmation gate, origin pinning,
  URL allowlist, audit redaction, and simulated destructive demo
  actions are byte-for-byte the same as v0.2.1.
• @marmarlabs scope unchanged.
• All 86 existing tests still pass; the new mcp-config test brings
  the count up.
• Workspace dep ranges remain ^0.2.0 — 0.2.2 satisfies the range,
  no consumer migration required. v0.2.0 and v0.2.1 remain functional
  on npm.

Setup commands users will see

OpenAI Codex CLI (one-liner):

codex mcp add agentbridge -- npx -y @marmarlabs/agentbridge-mcp-server

OpenAI Codex ~/.codex/config.toml:

[mcp_servers.agentbridge]
command = "npx"
args = ["-y", "@marmarlabs/agentbridge-mcp-server"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Same server, same safety story — also wired up for Claude Desktop,
Cursor, and custom MCP clients via
docs/mcp-client-setup.md.

Reporting issues

• Public bugs / feature requests:
  https://github.com/marmar9615-cloud/agentbridge-protocol/issues
• Security issues: see SECURITY.md. Do not
  open a public issue.

v0.2.1 — README Cleanup Patch

v0.2.1 — README cleanup patch

Date: 2026-04-27
Status: Stable patch release on top of v0.2.0. Same code, cleaner docs.

v0.2.1 is a docs-only patch over v0.2.0. There are no code,
behavior, schema, or build-output changes — the published tarballs are
identical to v0.2.0 in everything that runs at runtime, with refreshed
README and metadata files.

The reason for the patch: the README files bundled inside the v0.2.0
npm tarballs still described AgentBridge as "Public beta (v0.2.0)" in
their Status sections. That's the wording that ends up on each
package's npmjs.com page and renders inside npm view <pkg>, so users
discovering the project on npm could reasonably assume the packages
were unpublished or pre-release. v0.2.1 fixes the wording on all six
published packages so the public npm presentation matches reality.

What changed

• All six published READMEs reframe the Status block:
  • @marmarlabs/agentbridge-core
  • @marmarlabs/agentbridge-sdk
  • @marmarlabs/agentbridge-scanner
  • @marmarlabs/agentbridge-openapi
  • @marmarlabs/agentbridge-cli
  • @marmarlabs/agentbridge-mcp-server
• examples/nextjs-basic/README.md drops the "not yet published to
  npm — source-only" callout and points at the published
  @marmarlabs/* packages for installation.
• docs/roadmap.md Phase 3A heading reframed from
  "Public beta release hardening (shipped 0.2.0-beta)" to
  "npm release hardening (shipped 0.2.0 / 0.2.1)".
• docs/npm-publishing.md updated to use @marmarlabs for the
  login scope, registry config, and recovery commands, document the
  --userconfig token flow for non-interactive publishes, and use a
  stable (non-prerelease) gh release create example.

What did not change

• No package APIs, schemas, or runtime behavior.
• All 86 tests still pass on Node 20.x and 22.x.
• All safety invariants are preserved (confirmation gate, origin
  pinning, URL allowlist, audit redaction, simulated destructive
  demo actions).
• The manifest schema (still v0.1) is unchanged.
• Workspace dependency ranges remain ^0.2.0. 0.2.1 satisfies the
  range — consumers do not have to update anything to pick up v0.2.1.
• v0.2.0 remains functional. v0.2.1 is a refresh, not a replacement —
  applications pinned to 0.2.0 continue to work.
• v0.2.0-beta on GitHub has been superseded; the corresponding tag and
  prerelease have been removed in favour of the stable v0.2.0 / v0.2.1
  releases.

Install

# Author manifests in your own app
npm install @marmarlabs/agentbridge-sdk @marmarlabs/agentbridge-core

# Run the CLI
npx @marmarlabs/agentbridge-cli scan http://localhost:3000

# Run the MCP server
npx @marmarlabs/agentbridge-mcp-server

For Claude Desktop / Cursor wiring see
docs/mcp-client-setup.md.

Reporting issues

• Public bugs / feature requests:
  https://github.com/marmar9615-cloud/agentbridge-protocol/issues
• Security issues: see SECURITY.md. Do not
  open a public issue.

v0.2.0 — First Public Release

v0.2.0 — First Public Release

Date: 2026-04-27
Status: First public npm release. Packages live under the
@marmarlabs scope.

AgentBridge is an AI-native action layer for web apps. Web apps
publish a machine-readable manifest at /.well-known/agentbridge.json
declaring their structured actions. AI agents discover and invoke those
actions through an MCP server that enforces safety guarantees
(confirmation gates, origin pinning, audit logging, idempotency keys).

Honest status

AgentBridge v0.2.0 is usable today for:

• Local development and prototyping.
• Authoring and validating manifests.
• Scanner-driven readiness audits of any AgentBridge surface.
• Converting OpenAPI 3.x documents into draft AgentBridge manifests.
• Wiring AgentBridge actions into MCP-speaking agents (Claude Desktop,
  Cursor, custom clients).

It is not yet production security infrastructure. The following are
on the roadmap but not in 0.2.0:

• Signed manifests — a consumer cannot cryptographically verify a
  manifest's publisher.
• OAuth scope enforcement — permissions[] on actions is
  documentary; the MCP server does not check the agent's bearer token
  scopes.
• HTTP MCP transport — the bundled MCP server speaks stdio only.
• Distributed audit storage — the audit log is a local JSON file.

See docs/roadmap.md for the full roadmap.

Install

# Author manifests in your own app
npm install @marmarlabs/agentbridge-sdk @marmarlabs/agentbridge-core

# Run the CLI
npx @marmarlabs/agentbridge-cli scan http://localhost:3000

# Run the MCP server
npx @marmarlabs/agentbridge-mcp-server

Or clone the repo for development:

git clone https://github.com/marmar9615-cloud/agentbridge-protocol.git
cd agentbridge-protocol
npm install
npm run dev   # demo on :3000, Studio on :3001

Packages

Package	What it is
@marmarlabs/agentbridge-core	Schemas, types, validation, audit log helpers.
@marmarlabs/agentbridge-sdk	defineAgentAction, manifest builder, route handler glue.
@marmarlabs/agentbridge-scanner	0–100 readiness scoring with structured checks.
@marmarlabs/agentbridge-openapi	OpenAPI 3.x → AgentBridge manifest converter.
@marmarlabs/agentbridge-cli	agentbridge CLI: scan, validate, init, generate, mcp-config.
@marmarlabs/agentbridge-mcp-server	stdio MCP server with confirmation tokens, origin pinning, idempotency.

Quickstart

Scaffold a manifest

npx @marmarlabs/agentbridge-cli init
# writes agentbridge.config.ts and public/.well-known/agentbridge.json

Score a URL

npx @marmarlabs/agentbridge-cli scan http://localhost:3000

Validate a manifest

npx @marmarlabs/agentbridge-cli validate ./public/.well-known/agentbridge.json
# accepts file paths or URLs

OpenAPI import

Take an existing OpenAPI 3.x doc and turn it into a draft manifest:

npx @marmarlabs/agentbridge-cli generate openapi ./your-api.openapi.json \
    --base-url https://api.example.com \
    --out ./public/.well-known/agentbridge.json

Risk inferred from HTTP method (GET → low, POST/PUT/PATCH → medium,
DELETE → high). Always review before publishing. See
docs/openapi-import.md for the full guide.

MCP setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentbridge": {
      "command": "npx",
      "args": ["@marmarlabs/agentbridge-mcp-server"],
      "env": { "AGENTBRIDGE_ALLOW_REMOTE": "false" }
    }
  }
}

Restart Claude Desktop. Five tools should appear:
discover_manifest, scan_agent_readiness, list_actions,
call_action, get_audit_log.

See docs/mcp-client-setup.md for Cursor and
custom clients.

Safety invariants enforced today

These are tested and locked down:

Invariant	Test
Risky actions require explicit confirmationApproved: true AND a single-use, input-bound confirmationToken.	apps/mcp-server/src/tests/call-action.test.ts
Action endpoints must share origin with manifest.baseUrl.	same
Loopback-only URLs by default; AGENTBRIDGE_ALLOW_REMOTE=true is the only escape.	same
Audit redaction strips authorization, cookie, password, token, secret, api_key recursively.	packages/core/src/tests/audit.test.ts
Demo-app destructive actions are simulated; no real services touched.	apps/demo-app/lib/actions.ts

Versioning policy

• Manifest schema is stable for the v0.x line. Field additions are
  non-breaking; field removals or shape changes will bump to 1.0.
• Public package APIs may shift between 0.x releases — not casually,
  but not promised. Pin to ~0.2.0 if you need a stable surface; pin
  to ^0.2.0 if you want patches.

Reporting issues

• Public bugs / feature requests:
  https://github.com/marmar9615-cloud/agentbridge-protocol/issues
• Security issues: see SECURITY.md. Do not
  open a public issue.

Acknowledgements

Built on the Model Context Protocol
and Zod.