agent-bridge MCP server
Commit Nov 8, 2026Enables AI agents to message each other and hand off work across different tools, sessions, and machines using MCP, CLI, or Node.
Also known as creatornader/agent-bridge
- Stars
- 6
- Tools
- 15
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- Apache-2.0
What is agent-bridge MCP?
agent-bridge enables AI agents to message each other and hand off work across different tools, sessions, and machines using MCP, CLI, or Node. It exposes 15 tools, such as post_context, get_context, ack_context.
Summary generated from the project's README
About agent-bridge MCP server
Agent Bridge enables AI agents to communicate and hand off tasks across different tools, sessions, and machines. It provides a messaging layer that allows agents to send work to one another, even if the receiving agent is currently offline. Messages are preserved and wait for the recipient to become available, ensuring continuity across restarts.
Developers can use this system through MCP, a CLI, a Node library, or an authenticated HTTPS gateway. For single-machine setups, it operates in local mode using SQLite WAL, requiring no external accounts or services. For cross-machine communication, the gateway mode uses PostgreSQL as the central authority alongside a local SQLite edge store to manage presence, retries, and claims.
This tool supports various client identities including Claude Desktop, Claude Code, and Codex. It manages complex delivery logic such as atomic claims, lease renewals, and idempotency to prevent duplicate task execution. By using specific storage backends like PostgreSQL or SQLite, it scales from simple local testing to distributed multi-agent environments.
What you can do with it
- 1Asynchronous agent handoffsAn AI agent can send a task to another agent that is currently offline and have the message wait for its return.
- 2Distributed multi-machine messagingConnect agents running on different physical machines using a PostgreSQL backend.
- 3Local development without accountsSet up a private messaging environment on a single machine without needing any external services or credentials.
Written from the project's README. Every use case is checked against a quote from it.
agent-bridge MCP tools 15
Detected from the READMEpost_contextget_contextack_contextsendhistoryclaimextendacknowledgenegative_acknowledgelist_deliverieslist_delivery_eventscancel_delivery
Show all 15 toolsShow fewer tools
requeue_deliveryheartbeatpresence
Configuration
AGENT_BRIDGE_AGENTAGENT_BRIDGE_CLIENT_TOKENAGENT_BRIDGE_DATABASE_URLAGENT_BRIDGE_DR_SOURCE_DATABASE_URLAGENT_BRIDGE_DR_TARGET_DATABASE_URLAGENT_BRIDGE_HOSTAGENT_BRIDGE_MEMBERSHIP_REQUESTAGENT_BRIDGE_OPERATOR_DATABASE_URLAGENT_BRIDGE_OPERATOR_LOGINAGENT_BRIDGE_OPERATOR_PASSWORDAGENT_BRIDGE_PORTAGENT_BRIDGE_PROVIDERAGENT_BRIDGE_PROVISION_REQUESTAGENT_BRIDGE_REVOKE_REQUESTAGENT_BRIDGE_RUNTIME_DATABASE_URLAGENT_BRIDGE_URLAGENT_BRIDGE_WORKSPACEENROLLMENT_FILEMEMBERSHIP_REQUESTOPERATOR_LOGINOPERATOR_PASSWORDPROVISION_REQUESTREVOKE_REQUESTROTATE_REQUESTROTATION_FILE
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecreatornader/agent-bridge is public and reachablegithub.com/creatornader/agent-bridge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/creatornader/agent-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model15 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgent Bridge
Agent Bridge lets AI agents message each other and hand off work across tools, sessions, and machines. Messages wait while an agent is offline and are still there after it restarts.
Use it through MCP, a CLI, a Node library, or an authenticated HTTPS gateway. Start locally with SQLite. Use PostgreSQL when agents need to communicate across machines.
It supports two operating modes:
| Mode | Store | Use case |
|---|---|---|
| Local | SQLite WAL | One machine, no service or account |
| Gateway | PostgreSQL plus a local SQLite edge store | Cross-machine messaging, offline sends, claims, retries, and presence |
PostgreSQL is the authority in gateway mode. SQLite holds local-only messages or gateway edge state. Supabase can host PostgreSQL, but Agent Bridge does not depend on its client APIs. The direct Supabase runtime adapter was removed in 0.6.0.
Quick start
Install the published package and run a two-principal local proof. Local mode needs no account, daemon, or external database.
npm install --global @creatornader/agent-bridge
agent-bridge init --provider local
agent-bridge demo
Install Agent Bridge into a supported client after the demo succeeds:
agent-bridge clients install codex --identity codex
agent-bridge clients install claude-code --identity claude-code
agent-bridge clients install claude-desktop --identity claude-desktop
Restart the client, then run agent-bridge doctor --json if the MCP server does not
attach. The troubleshooting guide covers executable paths,
client configuration, and recovery steps.
Long-lived loopback MCP host
The normal adapters start Agent Bridge through stdio. A machine with many long-lived agent sessions can instead run one public Agent Bridge loopback host for each client identity. This reduces duplicate edge-store writers without turning the host into a shared identity or credential boundary.
On macOS, use the public package to install the host with the backend path and stable
instance returned by clients install or clients inspect:
agent-bridge-loopback-host --install-launchd \
--service-name codex \
--config ~/.agent-bridge/clients/<codex-backend>.config \
--agent codex \
--instance <stable-key> \
--port 8794
curl --fail http://127.0.0.1:8794/mcp/health
agent-bridge clients update codex --identity codex --instance <stable-key> \
--mcp-url http://127.0.0.1:8794/mcp --apply
Run the same command with a distinct service name, backend file, identity, stable
instance, and port for Claude Code. The readiness check is the health request, not a
launchd process state or a log line. The launchd contract intentionally omits priority
and background process hints because macOS can keep a Node process alive without
letting it bind its socket under those hints. Use --uninstall-launchd --service-name <name> --port <port> only after the client has moved back to a direct stdio
registration or another verified host. It waits for the listener to close.
Run the gateway with Compose
The repository includes a loopback-only Compose stack for development and evaluation. It starts PostgreSQL 16, runs the ordered migrations, creates a restricted runtime login, and starts the authenticated gateway.
mkdir -m 700 .secrets
node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > .secrets/postgres_password
node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > .secrets/runtime_password
chmod 600 .secrets/*
docker compose up --build --wait gateway
curl --fail http://127.0.0.1:8787/readyz
The checked-in stack publishes the gateway and PostgreSQL only on loopback. It is not a production TLS deployment. Read the deployment guide before exposing a gateway, changing network bindings, upgrading the schema, or relying on the named volume for persistent data.
The repository also maintains a Fly.io reference that does not depend on a specific
database host. It lives at
deploy/fly.toml. It deliberately omits an app name and release
command. Check the local contract before creating or changing any Fly resource:
npm run preflight:fly -- --json
Before migrating an existing PostgreSQL database, run the read-only production preflight with schema-owner authority:
AGENT_BRIDGE_DATABASE_URL="..." npm run preflight:postgres:production -- --json --require-ssl
The command checks the PostgreSQL major, database and role authority, existing
migration ledger, derived-role collisions, and the legacy shared_context import
shape inside a read-only transaction. authority.roles reports migration capability:
the schema owner may be a true superuser or a managed-provider administrator with
CREATEROLE. authority.native_dr reports source-backup capability. The source normally
connects as the schema owner, which must be a true superuser or hold BYPASSRLS, so
CREATEROLE alone can run migrations but cannot create a native backup. A restore target
uses its superuser session to validate a suspended restored schema-owner shell. The
migration suite tests both authority forms on PostgreSQL 15 through
18. The command does not print the connection URL or apply DDL. --require-ssl rejects
an unencrypted public database connection. Passing the preflight does not replace a
backup or authorize migration. When a session pooler terminates TLS, the check inspects
the client socket instead of the pooler's separate database connection.
After an operator supplies an existing app, npm run preflight:fly -- --app <app> --json adds read-only account, app, machine, config, and secret-name observations.
The command does not deploy, migrate, scale, restart, or print environment-variable
values. The Fly production procedure
keeps database migration and runtime-role bootstrap outside the gateway process.
The Fly gateway expects two secrets: the restricted runtime database URL and a
base64-encoded PostgreSQL CA bundle. It decodes the CA in memory and verifies both the
certificate chain and database hostname. It never needs a CA file inside the image.
Build the production image with its source revision, then confirm the running gateway before moving clients or starting the full proof:
fly deploy --config deploy/fly.toml --app <app> \
--build-arg AGENT_BRIDGE_BUILD_REVISION="$(git rev-parse HEAD)"
AGENT_BRIDGE_URL="https://<app>.fly.dev" AGENT_BRIDGE_TOKEN="..." \
npm run verify:gateway:release -- \
--version "$(node -p "require('./package.json').version")" \
--revision "$(git rev-parse HEAD)"
The authenticated check compares the running package and Git revision with the intended release. It also requires protocol 2.1, request authority, and row isolation. It prints no credential. A missing or different revision stops the rollout.
Release tags run this deployment gate before npm publication. After the package is
published, the workflow creates the immutable GitHub Release for the same tag with
the canonical title Agent Bridge v<version>. The release environment
must define AGENT_BRIDGE_FLY_APP and AGENT_BRIDGE_GATEWAY_ORIGIN, and keep
FLY_API_TOKEN plus RELEASE_VERIFY_TOKEN as protected secrets. The manual gateway production proof workflow tests the deployed gateway after this gate passes. GitHub
must run it from main in the protected
agent-bridge-production-proof environment. Separate sender and receiver jobs prove
offline outbox replay, exact idempotency, claim, and acknowledgment. The workflow then
restarts the single Fly machine, requires a later successful machine start event, and
verifies the message and settled delivery with a fresh receiver instance and a new
SQLite edge file. Use a new proof workspace for each release run. Owner provisioning
refuses a second agent with the same principal in one workspace, and revoked proof
credentials cannot be rotated.
Its versioned receipts contain only identifiers, times, principal and workspace labels,
the gateway origin, checks, and SHA-256 host evidence. They omit credentials, database
URLs, message content, and SQLite files.
What v2 provides
- Immutable messages with UUIDv7 IDs and opaque server cursors.
- Indexed source, thread, timestamp, workspace, and delivery queries.
- Read receipts separated from executable delivery state.
- Atomic claim, lease renewal, acknowledgment, negative acknowledgment, retry, and dead-letter operations.
- Immutable publisher-owned delivery policy with mailbox and leased modes, strict urgent/high/info claim priority, publisher cancel and requeue controls, authorized audit pagination, and fenced leases.
- Append-only delivery transition history.
- Idempotency conflict detection. Exact replay deduplicates; changed content under the same key fails.
- Scoped credentials that bind a remote workspace and agent principal.
- SQLite outbox and inbox cache for gateway clients.
- Leased instance-keyed presence with capabilities.
- MCP, CLI, HTTPS, and Node library access, plus host adapters for Codex, Claude Code, Claude Desktop, OpenClaw, and generic MCP clients.
- Canonical portable archives for messages and read receipts across local SQLite and shared PostgreSQL stores.
- Native SQLite and PostgreSQL backup, verification, and restore.
- Existing
post_context,get_context,ack_context,post, andgetbehavior during migration.
The accepted protocol and storage decisions live in docs/architecture-v2.md.
The canonical v2 operation registry generates JSON Schema, OpenAPI 3.1.2, and the MCP manifest. Use GET /v2/capabilities, MCP capabilities, or CLI agent-bridge capabilities to discover the operations for that surface and provider. Capabilities distinguish the current, selected, and supported protocol versions.
Authenticated gateway capabilities also report implementationVersion. Production
images report implementationRevision when the operator supplies the Git revision at
build time. These fields identify deployed code. They do not change protocol version
negotiation.
Protocol 2.1 uses a gateway-first rollout. An upgraded gateway continues to serve released 2.0 clients, including headerless requests and their direct or null delivery results. A 2.1 client probes before mutation and proceeds only when complete, consistent response headers select 2.1 and advertise 2.1 support. It rejects mutation against a headerless or 2.0 gateway instead of downgrading. Upgrade the gateway before installing or starting 2.1 clients.
Two gateway-only HTTP 2.1 operations establish a short-lived endpoint-migration challenge. Initial preflight uses a direct predecessor and successor. After a cutover journal exists, the same active successor credential can issue at the retained source URL and consume at the target URL. Both calls require active transaction-bound authority and use the canonical credential and operation rate buckets. PostgreSQL stores only a domain-separated SHA-256 commitment. A challenge expires within 60 seconds and does not authorize endpoint cutover. Authenticated HTTP 2.1 capabilities include the credential's grantedScopes.
The OpenAPI paths describe protocol 2.1. The embedded x-agent-bridge-protocol-2.0 and x-agent-bridge-schemas-2.0 vendor extensions contain frozen compatibility schema metadata for released 2.0 clients. They are not a second OpenAPI description. Gateway credentials enforce the operation scopes declared by the canonical registry. Local mode uses process identity. Provider-neutral artifacts report this difference instead of claiming one authorization model for every backend.
Architecture
flowchart TB
subgraph execution["Agent execution"]
harnesses["Agent harnesses<br/>product-specific or custom"]
callers["Non-harness callers<br/>scripts, CI jobs, and application services"]
end
subgraph hosts["Host surfaces"]
clis["Command-line hosts<br/>Codex CLI and Claude Code CLI"]
desktops["Desktop hosts<br/>Codex in ChatGPT and Claude Desktop"]
daemons["Daemons and custom MCP hosts"]
end
subgraph access["Integration and access"]
adapter["Host adapter or MCP registration"]
mcp["MCP over stdio: agent-bridge-mcp"]
cli["CLI: agent-bridge"]
library["Node library"]
direct["Direct HTTPS client"]
end
harnesses --> clis
harnesses --> desktops
harnesses --> daemons
clis --> adapter
desktops --> adapter
daemons --> adapter
adapter --> mcp
callers --> cli
callers --> library
callers --> direct
mcp --> core["Agent Bridge client core<br/>principal plus optional consumer instance key"]
cli --> core
library --> core
core --> local["Local mode<br/>SQLite authority"]
core --> edge["Gateway client mode<br/>SQLite edge outbox and cache"]
edge -->|"HTTPS protocol 2.1"| gateway["Agent Bridge gateway"]
direct -->|"HTTPS protocol 2.1"| gateway
gateway --> postgres["PostgreSQL authority"]
The diagram shows concepts, not exclusive product categories. A product may package a harness and a host together. A harness is the agent execution environment. A host is the CLI, desktop app, or daemon where it runs. A host adapter registers an access surface. Scripts are orthogonal callers: they can invoke the CLI, call HTTPS, or embed the Node library without becoming agent harnesses.
| Adapter or integration | Host coverage | Access | Installation status |
|---|---|---|---|
codex |
Codex CLI and Codex in the ChatGPT desktop app through their shared profile | MCP stdio | Automated |
claude-code |
Claude Code terminal harness | MCP stdio | Automated |
claude-desktop |
Claude Desktop application | MCP stdio | Automated |
openclaw |
OpenClaw host or daemon | MCP stdio | Manifest included; operator-managed |
generic-mcp |
Any compatible stdio MCP host | MCP stdio | Manifest included; operator-managed |
| Scripts and services | Shell jobs, CI, daemons, and application code | CLI, HTTPS, or Node library | Direct integration |
| Hermes, Pi, and other harnesses | Depends on the host's supported interface | No interface assumed | No dedicated adapter or conformance claim yet |
agent-bridge-mcp is a stdio server. The gateway exposes the Agent Bridge HTTPS API;
it is not MCP over HTTP. A direct HTTPS client can bypass MCP, the CLI, and the local
edge store, but then owns its own retry and offline behavior.
Realtime notifications or hooks may wake a client, but cursored reads remain authoritative. A missed notification does not lose a message.
A2A and application task semantics sit above Agent Bridge. MCP, CLI, HTTPS, and the Node library are access surfaces. Optional transports such as SLIM or NATS may provide wakeups or transport below the core, but authoritative recovery still uses cursored pull. agmsg remains a reference for adapters, interoperability, and client experience.
ADR-0001 defines this boundary and the distinct acknowledgment meanings. ADR-0003 defines the host layers and consumer instance-key contract.
Agent Bridge is not a workflow engine, scheduler, memory system, terminal manager, or new universal agent protocol. See Agent Bridge in the agent ecosystem for its relationship to MCP, A2A, agmsg, brokers, and agent runtimes.
Requirements
- Node.js 22.23.1 or newer.
- SQLite 3.51.3 or newer for local and edge storage. The supported Node version includes it.
- Concurrent local and edge initialization may wait up to 15 seconds for schema work. File-backed local and edge stores serialize mutations with a durable token-checked lease, so independently launched MCP clients do not contend as SQLite writers.
- PostgreSQL 15, 16, 17, or 18 for gateway mode. New PostgreSQL majors fail the migration prerequisite and live readiness checks until their catalog digest is certified.
Install from source
Use the source install for development. The normal installation path is the published
@creatornader/agent-bridge package shown in the quick start. The unscoped npm name
belongs to another project, and npm rejects agentbridge as confusingly similar.
git clone https://github.com/creatornader/agent-bridge.git
cd agent-bridge
npm ci
npm run build
npm link
The package exposes three executables:
agent-bridge: CLI.agent-bridge-mcp: stdio MCP server.agent-bridge-gateway: HTTP gateway.
npm pack builds the package before creating a tarball. CI installs that tarball into an empty project, imports the provider-neutral library API, and runs the packaged CLI. Importing the package root does not start the MCP server.
Client identities and local commands
Initialize backend settings. init does not write an agent identity into the shared config.
agent-bridge init --provider local
Each client supplies its own identity:
AGENT_BRIDGE_AGENT=codex agent-bridge send \
--target claude-code \
--type context \
"Bridge is ready"
AGENT_BRIDGE_AGENT=claude-code agent-bridge inbox --receipt-state unread
You can also pass --source to a standalone send. If the process already has AGENT_BRIDGE_AGENT, an explicit identity must match it.
The post, get, and --unacked-by forms remain available only for compatibility
with older clients. New integrations should use send, caller-bound inboxes, and
--receipt-state.
Portable archives
Portable archives move one workspace's immutable messages and read receipts between
canonical local SQLite and PostgreSQL stores. Export writes a private file through a
same-directory temporary file, file fsync, atomic publication, and directory fsync.
The export audit completes only after durable publication. A failed export records a
bounded abandonment code. Export and import paths must satisfy the current user's
private-path policy. Export refuses to replace an existing file unless --force is
present. Export accepts --request-id, embeds it as exportRequestId in the archive
header, and returns it on success. Verification and import also return that export
provenance. An import request ID is a separate destination operation identifier.
Reusing an export request ID verifies a completed file or reconciles a matching file
whose audit response was lost. A missing or mismatched file stays started and requires
a new export request ID or owner reconciliation. Recovery artifacts use deterministic
same-directory names derived from the export request ID, so a retry can report and
clean only its own private temporary file or backup. Force replacement keeps that
backup until the new file is durable. Errors report whether publication, backup
cleanup, or audit state is known.
Portable v1 accepts only records in the current Agent Bridge domain. New API writes use lowercase UUIDs. Archives require lowercase UUIDs and UTC timestamps with six fractional digits. They do not trim strings, remove duplicates, apply defaults, or rewrite message content. Export rejects legacy or direct database rows outside these rules. Recover those rows through native database backup and restore tools.
install -d -m 700 "$HOME/.agent-bridge/archives"
agent-bridge archive export \
--provider local \
--workspace team \
--request-id 00000000-0000-4000-8000-000000000001 \
--db "$HOME/.agent-bridge/bridge.sqlite3" \
--output "$HOME/.agent-bridge/archives/team.ndjson"
agent-bridge archive verify --file "$HOME/.agent-bridge/archives/team.ndjson"
# Import is a rollback-backed dry run unless --apply is explicit.
agent-bridge archive import \
--provider local \
--db /path/to/target.sqlite3 \
--file "$HOME/.agent-bridge/archives/team.ndjson" \
--workspace team \
--dry-run
agent-bridge archive import \
--provider local \
--db /path/to/target.sqlite3 \
--file "$HOME/.agent-bridge/archives/team.ndjson" \
--workspace team \
--request-id 00000000-0000-4000-8000-000000000001 \
--apply
Local commands use --db, AGENT_BRIDGE_DB, the selected shared config, or the
canonical local database path, in that order. PostgreSQL commands accept database
authority only from AGENT_BRIDGE_ARCHIVE_DATABASE_URL and require a login registered
for the archive boundary created by the current migrations. They do not fall back to
the schema-owner, gateway runtime, owner-control, or client database settings.
The archive digest detects accidental changes to the canonical bytes. It is neither
encryption nor authentication. Archives contain message content and routing metadata,
so protect them as private data. They exclude deliveries, delivery events, presence,
credentials, owner-control records, security events, and other control or security
state. The library API is available from @creatornader/agent-bridge/archive.
Import opens the archive once without following links. It verifies the file, replays
messages, then replays receipts through the same descriptor. Every pass checks framing,
order, counts, and the client-computed digest. Batches are limited by row count and a
4 MiB byte budget. --dry-run and --apply are mutually exclusive.
agent-bridge MCP questions
What tools does agent-bridge MCP provide?
It exposes 15 tools, including post_context, get_context, ack_context, send, history.
Which AI clients are supported?
Agent Bridge supports clients such as Codex, Claude Code, Claude Desktop, and OpenClaw.