Skip to main content

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.

The Marfa MCP server is the canonical agent surface for a Marfa tenant. It speaks the Model Context Protocol 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

# 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.
VariableDescription
MARFA_API_URLMarfa server URL (required; no default)
MARFA_API_KEYAPI key for authentication
MARFA_MCP_TOOLSETSComma-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: 
{
  "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 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. Single src/index.ts (~2200 lines) — tool registrations, SDK client initialisation, stdio transport wiring. Build and code rules in the repo’s CLAUDE.md.