> ## 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.

# MCP server

> @withmarfa/mcp — Model Context Protocol server exposing the Marfa API to Claude and other MCP clients

The Marfa MCP server is the canonical agent surface for a Marfa tenant. It speaks the [Model Context Protocol](https://modelcontextprotocol.io/) over stdio, registers one tool per SDK method, and translates each tool call into a single `@withmarfa/sdk` invocation. Stateless between calls, Zod-validated inputs, JSON outputs.

Published to npm as `@withmarfa/mcp`. Wraps the TypeScript SDK; every operation the SDK exposes is reachable as an MCP tool.

## Install

```bash theme={null}
# One-shot via npx (no install)
npx -y @withmarfa/mcp

# Or install globally to get a `marfa-mcp` binary on PATH
npm install -g @withmarfa/mcp
```

The same `@withmarfa/sdk` releases the CLI consumes drive the MCP — both pin caret-ranged on the published SDK.

## Configure

Three environment variables drive runtime configuration. `MARFA_API_URL` is required; the server exits at startup if unset.

| Variable             | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `MARFA_API_URL`      | Marfa server URL (required; no default)                                           |
| `MARFA_API_KEY`      | API key for authentication                                                        |
| `MARFA_MCP_TOOLSETS` | Comma-list of toolsets to enable: `standard`, `admin`, `all`. Default: `standard` |

The same value can be passed as a CLI argument: `--toolsets standard,admin`. The CLI argument takes precedence over the environment variable.

One Marfa tenant per server process. A user with multiple tenants configures multiple MCP-server entries in their client.

## Connect

### Claude Code

Add to `~/.claude.json` under `mcpServers`. Uses `npx` for zero-install:

```json theme={null}
{
  "mcpServers": {
    "marfa": {
      "command": "npx",
      "args": ["-y", "@withmarfa/mcp"],
      "env": {
        "MARFA_API_URL": "https://your-server.example.com",
        "MARFA_API_KEY": "marfa_k1_...",
        "MARFA_MCP_TOOLSETS": "all"
      }
    }
  }
}
```

If you've installed globally with `npm i -g @withmarfa/mcp`, `"command": "marfa-mcp"` (no args) works too.

### Claude Desktop

Same `mcpServers.marfa` block in `~/Library/Application Support/Claude/claude_desktop_config.json`. Cmd-Q and relaunch to pick up changes — `/reload-plugins` doesn't restart MCP subprocesses.

### Other MCP clients

Any MCP-compatible client (Cline, Continue, custom hosts) works the same way — point its server-spawn config at `npx -y @withmarfa/mcp` or the globally-installed `marfa-mcp` bin, and pass the env vars through.

## Toolsets

The tool surface is partitioned into two named toolsets. `standard` is on by default; `admin` is opt-in. Pass `all` to enable both. The split keeps context-window cost low for clients that load every tool definition on connect.

### `standard` (default, 27 tools)

Daily-driver reads, writes, tagging, search, edges, type discovery, profile, and the attachments composite.

* **Items** — `create_item`, `upsert_item`, `get_item`, `update_item`, `delete_item`, `restore_item`, `list_items`, `search_items`, `transition_item`, `list_versions`, `create_item_with_attachments`
* **Metadata** — `get_metadata`, `tag_item`, `untag_item`, `set_metadata`, `merge_metadata`, `list_tags`
* **Edges** — `create_edge`, `update_edge`, `delete_edge`, `list_edges`, `list_edges_from`, `list_backrefs`, `list_edge_types`
* **Types (read)** — `list_types`, `describe_type`
* **Profile** — `profile_get`

### `admin` (opt-in, 15 tools)

Operator-flavored surface: bulk operations, type and edge-type registration, raw extension and blob I/O.

* **Bulk** — `bulk_items`, `bulk_action_items`, `bulk_edges`
* **Types (write)** — `register_type`, `update_type`, `delete_type`
* **Edge types (write)** — `create_edge_type`, `delete_edge_type`
* **Extensions** — `get_extensions`, `set_extension`, `delete_extension`
* **Blobs** — `upload_blob`, `download_blob`, `blob_exists`, `get_blob_url`

## Tool design

A few conventions worth knowing before reaching for the surface:

* **Every tool is a single SDK call.** No composition, no retries beyond what the SDK does, no caching. The server is stateless between calls — perfect for the agent's "make one decision, call one tool" loop.
* **Outputs are JSON text.** Successes return a single text content block with the JSON-serialised result. Errors return an error block with the MarfaError code and message — `error.code` is the stable string, `error.message` is human-friendly prose.
* **Atomic item + edges on create.** `create_item` and `upsert_item` accept an `edges` payload (`{ "in-thread": [threadId] }`, `{ "about": [topicId] }`, etc.) so relationship setup lands in one call rather than two.
* **`upsert_item` returns `{ item, created }`.** Branch on the boolean to know whether you minted a new row or matched and updated an existing one. Pair with `source` + `source_id` for natural-key upsert.
* **Filter-DSL passes through.** `list_items` accepts the full filter grammar (`edge[type]=id`, `backref[type]=id`, tag filters, `tier`) so the model can query relationships without round-tripping through edge-listing tools.

## What MCP is not

The Marfa MCP server exposes tools only — no MCP resources, no prompts, no sampling. Each tool call is independent: no in-process cache, no cross-call state. The lever for context-window cost is **toolsets**, not a dispatcher tool or lazy schema loader.

It's also not a CLI. The [CLI](/clients/cli) is a terminal surface designed for human typing; MCP is an agent surface designed for an LLM reasoning about what to do next. Same SDK underneath, completely different ergonomics.

## Repo

Source at [`withmarfa/mcp`](https://github.com/withmarfa/mcp). Single `src/index.ts` (\~2200 lines) — tool registrations, SDK client initialisation, stdio transport wiring. Build and code rules in the repo's `CLAUDE.md`.