> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myme.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Clients

> In-house clients and the pattern for building your own

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`](https://github.com/withmarfa/marfa/tree/main/packages/sdk) |
| **Swift SDK**                      | Swift client for Apple platforms with remote / pure-local / synced modes.        | SwiftPM: `https://github.com/withmarfa/swift-sdk.git`        | [`withmarfa/swift-sdk`](https://github.com/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`](https://github.com/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`](https://github.com/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`](https://github.com/withmarfa/sync)                          |
| **Raycast extension**              | Browse, search, capture, and manage keys from Raycast on macOS.                  | Raycast Store: *Marfa*                                       | [`withmarfa/raycast`](https://github.com/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](/clients/sync) 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](/concepts/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](/clients/building-a-client) walks through the pattern using the MCP server as the worked example.