Clients

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

Client	Purpose	Install	Repo
TypeScript SDK	TypeScript client for Node.js, Bun, Deno, and browsers.	`npm install @withmarfa/sdk` or `pnpm add @withmarfa/sdk`	`withmarfa/marfa`
Swift SDK	Swift client for Apple platforms with remote / pure-local / synced modes.	SwiftPM: `https://github.com/withmarfa/swift-sdk.git`	`withmarfa/swift-sdk`
CLI (`@withmarfa/cli`)	Shell tool for inspecting, listing, and mutating items from a terminal.	`npm install -g @withmarfa/cli` — invoke as `my`	`withmarfa/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 config	`withmarfa/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-sync`	`withmarfa/sync`
Raycast extension	Browse, search, capture, and manage keys from Raycast on macOS.	Raycast Store: Marfa	`withmarfa/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.

Shape	What it is	Best for
Direct SDK client	The 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-mediated	The 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 Integration	A `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.

Get started

Concepts

API

Clients

First-party clients

Integration shapes

Building your own

​First-party clients

​Integration shapes

​Building your own

First-party clients

Integration shapes

Building your own