MongoDB for Flow Steward

An independent MongoDB extension with document reads and writes and bounded read-only aggregation. No database triggers. Install only this connector; it does not include SQL, Redis, or other database drivers.

Install

Choose the ZIP matching the Linux host architecture, not the machine running your browser:

• flowsteward.mongodb-1.0.1-linux-amd64.zip

• flowsteward.mongodb-1.0.1-linux-arm64.zip

Each ZIP contains one MongoDB-only Google MCP Toolbox executable, the host-v2 adapter, manifests, and source/build provenance. Verify SHA256SUMS before importing the archive. Flow Steward platform 1.4.0 or newer and public extension SDK 0.4.0 are required.

Related MCP server: MCP MongoDB

Connection

Create a project MongoDB connection with host and database. Use the server hostname alone, with no URI, credentials or path. The connection fixes the database; each workflow action selects a collection. Data is stored directly in your collection without an added tenant prefix. Database credentials and MongoDB roles control access, so use a user restricted to the intended database.

Store username and password in the secret fields. Credentials are never part of action inputs or returned diagnostics. Standalone, replica discovery and SRV connection paths are implemented. SRV requires TLS and the default port. Public endpoints always require TLS. Private endpoints also require the host administrator's FS_ALLOW_PRIVATE_REMOTE_URLS opt-in. Every discovered node is resolved and checked by the native dialer, then connected using its validated IP while retaining the TLS hostname. Custom certificate files, insecure TLS, arbitrary URI options, tunnels, and executable overrides are not exposed.

Actions

Every action requires connection_ref and collection.

Every result also includes collection; writes include applied. A matched update that changes nothing returns applied: false. Zero-match reads and deletes succeed normally. Filters on mutations must be nonempty; this does not prove selectivity, so review them before use. Many-document writes can affect all matching documents and are not limited to 100. Insert batches contain 1–100 documents. This connector offers operator updates and upserts; it does not expose replacement updates, transactions or change streams.

Reads return at most 100 documents (default 20); find_one returns at most one. Sorting preserves field order. Aggregation accepts at most 16 stages and appends the configured result limit. Allowed stages are $match, $project, $group, $sort, $limit, $skip, $unwind, $addFields, $set, $unset, $count, $replaceRoot, $replaceWith. Write stages, cross-collection joins and JavaScript operators/BSON code are rejected. A result limit bounds returned documents, not the server work needed by a sort or group. Requests are capped at 256 KiB; inline results at 480 KiB; native output at 1 MiB. Larger results fail with an explicit error; use narrower filters/projections.

BSON types and examples

Use JSON objects in JSON fields. Results use canonical MongoDB Extended JSON, preserving BSON types and 64-bit integer precision. Numbers in returned documents are tagged, for example {"$numberInt":"3"}. Write counters are ordinary JSON integers. To query an ObjectId returned by an insert, pass the returned inserted_id unchanged:

{"connection_ref":"my-mongodb","collection":"documents","filter":{"_id":{"$oid":"0123456789abcdef01234567"}}}

An upsert example:

{"connection_ref":"my-mongodb","collection":"documents","filter":{"slug":"intro"},"update":{"$set":{"title":"Introduction","revision":{"$numberLong":"9007199254740993"}}},"upsert":true}

Bare integers outside the interoperable JSON safe range are rejected; use $numberLong or the appropriate Extended JSON representation. String values containing ${ENV}, {{templates}}, or $operators remain literal data.

Writes and failure handling

Live writes require the host's durable external_effect_id claim. Test mode validates input and suppresses writes before starting Toolbox. Automatic MongoDB read/write retries are disabled and writes request majority acknowledgement. Neither the claim nor an insert batch makes a write transaction atomic: a timeout, broken connection or batch error may follow partial effects. Such failures report retryable: false and external_effect_status: timeout_unknown. Reconcile existing documents before deciding to retry. Stable explicit _id values help detect duplicate inserts. Do not automatically retry $inc, pushes, or partially completed batches.

Build and verify

./scripts/build_toolbox.sh
python3 scripts/package_extension.py --runtime-target linux-amd64
python3 scripts/package_extension.py --runtime-target linux-arm64

The build pins upstream Toolbox v1.3.0 commit b0010060a939455d91e4f8ba62dc3e72b1892469 and a Go container by digest. The included source patch corrects MongoDB sorting and result handling, adds literal payloads and the dial policy, and disables automatic retries. Binary SHA-256, source, patch and build image are recorded in toolbox-provenance.json. Binaries are built locally and omitted from Git source history. Archives have deterministic ordering, timestamps and permissions, contain one architecture, and stay within the installer's 50 MiB compressed/150 MiB unpacked limits.

From a Flow Steward checkout, run the supported container gate against this standalone checkout:

./core/entrypoints/cli/scripts/lint.sh --checks extension-static,extension-tests --extension-root /absolute/path/to/ext-data-mongodb

Unit tests cover contracts, input limits, literal data, write claims, failure semantics, transport deadlines and archive boundaries. Live tests opt in through ignored tests/live-mongodb.local.json with host, port, database, auth_source, username, password, tls. Use a disposable test database. They exercise authenticated document CRUD, Extended JSON, projection, sorting, upsert and aggregation. Without a fixture they are explicitly skipped. Local integration uses MongoDB 8.0.17; Atlas/SRV, replica failover and a real public TLS deployment require separate environment acceptance.

Apache-2.0. See LICENSE and NOTICE. This is an independent Flow Steward integration, unaffiliated with MongoDB, Inc.