mdbase connect

Important

Beta: The managed mdbase connect cloud service is transitioning from invite-only access to public signup. Existing invitation links remain valid.

mdbase connect lets you use the applications you choose with the Markdown data you control. An application gets access to one collection only after you approve the exact actions it can perform, and you can pause or revoke that access at any time.

Your collection can stay in a folder on your computer or be hosted by mdbase with an optional local Markdown mirror. Either way, it remains a standard mdbase collection rather than being moved into an application-specific database.

What you can do

• Connect websites and native applications to a local or hosted collection.
• Review concrete permissions such as reading, querying, creating, or updating records before granting access.
• Keep local collection folders private and make remote access available without opening an inbound port on your computer.
• Work directly on the same computer when possible, with automatic fallback to an encrypted relay when needed.
• Pause an application or immediately disable its Connect credentials; hosted revocation remains visibly pending until the data authority confirms it.
• Use your collections from MCP clients such as Claude and ChatGPT.
• Mirror a hosted collection to a local folder for Markdown-based tools and backups.
• Read, query and write your collections from the mdbase command line.

How it works

Collections on your computer

The mdbase connect desktop app registers your collection and runs a small background connector. Applications use a direct local connection when they are on the same computer. From elsewhere, requests travel through the managed relay, while the connector on your computer remains the final authority for every operation.

Your collection path is not sent to the cloud service, and you do not need to expose your computer to incoming internet connections.

Hosted collections

Hosted collections keep their authoritative Markdown with mdbase. You can optionally mirror a hosted collection to a folder on your computer and continue using file-based tools alongside connected applications.

Applications use the same approval model for local and hosted collections, so moving where a collection lives does not give an application broader access.

Getting started during the beta

To use the managed cloud service, create an account from the Connect sign-in page or follow an existing invitation link. Then:

1. Create or sign in to your mdbase connect account.
2. Install the desktop build provided for your platform.
3. Open the desktop app and pair your computer.
4. Add an existing mdbase collection or create a hosted collection.
5. In a compatible application, choose Connect collection and review the requested access before approving it.

The editor's Connect workspace is the main web place to manage collections, connected applications, computers, and account sessions. The desktop app owns local-folder and mirror administration. The Connect portal is intentionally limited to sign-in, pairing, recovery, and authorization transactions.

Connect an MCP client

The managed MCP endpoint is:

https://mcp.mdbase.dev/mcp

Add it as a remote or custom MCP connector in an OAuth-capable client. The first connection asks you to choose a collection and approve its access. Additional collections receive independent grants, so connecting one does not expose the others.

See the MCP gateway guide for supported tools and the gateway's trust boundary.

The mdbase plugin package bundles this endpoint with collection skills for ChatGPT and Codex. For local testing and directory submission, see ChatGPT and Codex plugin.

Release notes

See the changelog for breaking SDK/contract changes, durable mutation guarantees, upgrade requirements, recovery guidance, and platform preview limitations.

Build an application

The @mdbase-dev/connect SDK gives browser and native applications an authorized, collection-scoped client:

pnpm add @mdbase-dev/connect

Start with the five-minute quickstart or read the complete Connect SDK guide. The SDK supports authorization with PKCE, direct and relayed operations, hosted replication, change delivery, notifications, and portable downloaded applications.

Applications declare their data contracts and requested capabilities. If a collection needs a declared contract, mdbase connect shows that change during approval and installs it as one verified transaction. This does not give the application general permission to manage types or schemas.

Security and privacy

mdbase connect is designed so that granting useful access does not mean handing an application an entire folder or account:

• Each grant is tied to one application, one collection, and an explicit set of operations.
• The local connector enforces access at the computer that owns a local collection.
• Local collection paths never leave the computer.
• Browser-to-connector relay payloads are end-to-end encrypted. The managed relay can see routing metadata, operation timing, and payload sizes, but not record contents or operation results.
• Hosted Markdown is encrypted at rest using per-collection data keys.
• Pausing is enforced immediately. Revocation immediately disables Connect-issued credentials; a hosted authority rechecks access before each new operation or bounded file range and explicitly confirms completion.

The MCP gateway is an authorized application endpoint: it decrypts responses in memory so it can return them to the MCP client, but does not persist record payloads or operation results.

For the detailed trust model, see Architecture, Encryption, and Hosted collections. Security assumptions, abuse cases, and prerelease residual risks are collected in the Threat model. The source and test map for independent review is the explicitly unaudited Security audit preparation package. Please use the private reporting process in the Security policy for suspected vulnerabilities.

Command line

The desktop app includes the mdbase CLI and background daemon. The same native executable is also published as a standalone headless archive for Linux, macOS, and Windows.

mdbase status
mdbase collection add /path/to/notes
mdbase query --types task --where 'status == "open"'
mdbase read tasks/review.md
mdbase update tasks/review.md --fields '{"status": "done"}'
mdbase validate -c notes

Record commands work on the folder you are in, another with -C PATH, or a registered collection with -c; they go through the daemon when it serves the folder. Output is human-readable; --json prints machine-readable results. Run mdbase --help for the full list, and see the headless installation guide for verified standalone installation, service operation and record commands.

Self-hosting

mdbase connect is open-source, and advanced operators can run the control plane, relay, hosted collection provider, and MCP gateway themselves. Self-hosters are responsible for authentication, TLS, signing, upgrades, monitoring, backups, and incident response.

Use an immutable beta release tag rather than main, and follow the production self-hosting guide.

Contributing

This repository contains the editor, desktop app, CLI and connector, browser SDK, managed-service control plane and relay, hosted collection provider, MCP gateway, and shared protocols. These products release independently even though they share one workspace and lockfile.

See Contributing for change fragments, the architecture check, generated-file rebases, and automated beta version preparation.

Development requires a Rust toolchain, Node.js 24 LTS, and pnpm 11.15.1.

pnpm install
cargo test --workspace
pnpm build
pnpm typecheck
pnpm test

See the CI flake policy for bounded, recorded per-test retries and the retry-free nightly stress workflow.

The end-to-end suites cover the runtime daemon's request path, the encrypted relay, hosted replication, and the production hosted provider:

pnpm e2e
pnpm e2e:relay
pnpm e2e:sync
pnpm e2e:provider

Seeded functional stress profiles cover concurrent replicas, lost responses, restarts, compaction, mirror convergence, scale, and soak behavior:

pnpm stress:quick
pnpm stress:functional
pnpm stress:soak:smoke

To run the local development environment:

cp .env.example .env
pnpm dev:environment:up

The desktop app runs on an mdbn-daemon build: MDBN_DAEMON_BIN=<absolute path to mdbase> pnpm dev:desktop:fresh.

See Testing, Functional stress testing, Maintainability, Releasing, and Production self-hosting for the complete workflows.

License

MIT