Skip to main content
A client is anything that talks to a Marfa server through an SDK — an app, a CLI, an MCP server, a sync agent, a scheduled job. The WithMarfa org maintains a small set of first-party clients that exercise the SDK surface and ship as reference implementations.

​
First-party clients

ClientPurposeInstallRepo
TypeScript SDKTypeScript client for Node.js, Bun, Deno, and browsers.npm install @withmarfa/sdk or pnpm add @withmarfa/sdkwithmarfa/marfa
Swift SDKSwift client for Apple platforms with remote / pure-local / synced modes.SwiftPM: https://github.com/withmarfa/swift-sdk.gitwithmarfa/swift-sdk
CLI (@withmarfa/cli)Shell tool for inspecting, listing, and mutating items from a terminal.npm install -g @withmarfa/cli — invoke as mywithmarfa/cli
MCP server (@withmarfa/mcp)Exposes the API as MCP tools for Claude and other MCP hosts.npx @withmarfa/mcp — configure under the host’s MCP configwithmarfa/mcp
Sync agent (@withmarfa/sync)Mirrors a local folder into Marfa; captures markdown notes as core.note items.npm install -g @withmarfa/sync — invoke as marfa-syncwithmarfa/sync
Raycast extensionBrowse, search, capture, and manage keys from Raycast on macOS.Raycast Store: Marfawithmarfa/raycast
All first-party clients consume @withmarfa/sdk (TypeScript) or the Swift SDK; none re-implement the wire format.

​
Integration shapes

A client integrating with Marfa takes one of three shapes. The choice is about how the client talks to Marfa, not what runtime it runs in. Pick based on what produces the data and where it lives.
ShapeWhat it isBest for
Direct SDK clientThe client uses @withmarfa/sdk (TypeScript) or the Swift SDK to write items via the API. Authenticates with OAuth or an API key. Runs wherever the app already runs.Apps with structured data, multi-part outputs, or type-specific semantics. The most common shape.
Sync-mediatedThe client writes files to a folder; the sync agent watches the folder and translates files into Marfa items. No SDK code on the client side beyond writing files.Apps that already produce one-file-per-thing in a user-visible vault — markdown notes apps, image-capture apps producing single files.
Published IntegrationA system.integration manifest published to the marketplace, running on Marfa’s runtime substrate (Cloudflare Workers, or locally for runtime_compatibility: ["local"]). See Integrations.Connectors a user installs and configures — calendar sync, RSS pollers, cron-driven cleanup, scheduled polls of external APIs.
How to pick:
  • Structured data on the user’s own device? Direct SDK client.
  • Plain files in a vault? Sync-mediated.
  • Scheduled or event-driven against an external service? Published Integration.
The shapes aren’t exclusive. A Direct SDK app can also publish an Integration manifest if it wants to expose extras — a desktop app that’s mostly a direct-SDK client and additionally registers a scheduled-cleanup integration the user can opt into.

​
Building your own

The same SDK surface covers third-party clients — apps, integrations, ingest agents, workflow triggers, anything authenticated with a Marfa credential. Building a client walks through the pattern using the MCP server as the worked example.