Marfa MCP Server

Model Context Protocol server for the Marfa API. Exposes Marfa's items, metadata, edges, types, blobs, and bulk operations as MCP tools for Claude and any other MCP client. End-client surface — operator-shaped tooling (credentials, webhooks, space config, observability, connection lifecycle) lives on the CLI, not here.

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

Configure

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

Use with Claude Code

Add to ~/.claude.json under mcpServers:

{
  "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, "command": "marfa-mcp" (no args) works too.

Use with Claude Desktop

Add the same mcpServers.marfa block to ~/Library/Application Support/Claude/claude_desktop_config.json.

Toolsets

The server partitions its tools into named toolsets. Newcomers get a focused default surface; power users opt into the rest. This 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 host+attachments composite.

• Items — create_item, upsert_item, get_item, update_item, delete_item, restore_item, list_items, search_items, transition_item, list_versions
• 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
• Attachments composite — create_item_with_attachments

admin (opt-in, 15 tools)

Expressive end-client writes that the server admin-gates: bulk, type and edge-type registration, raw extension I/O, 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

Operator-shaped surfaces — credentials, webhooks, space config, observability (audit/metrics/stats), connection lifecycle, item purge — are deliberately not exposed here. Use the CLI or operator UI for those.

Pass all as shorthand for both: --toolsets all or MARFA_MCP_TOOLSETS=all.

Inputs and errors

Two conventions hold across every tool, and the second has one carve-out worth knowing before you write a client.

Inputs are closed. An unrecognized parameter is refused and the refusal names it, rather than being dropped on the way to the handler. A stripped key is worse than a rejected one for a model caller: a misspelled filter would otherwise come back as a successful call carrying everything the filter was meant to exclude, and nothing in the response would distinguish that from a filter that genuinely matched everything.

Errors from a tool are structured JSON, not prose — { "error": { "code", "message", "status", ... } }, with whatever else the failure carries alongside. That matters most where the recovery state is hard to reach any other way: update_edge refused on a stale version returns the edge as the server now holds it, and since this kit does not expose the server's single-edge read the alternative is re-listing to find it again.

One exception, and it is the common one. Schema validation happens in the MCP server kit, before a handler runs, so a refusal for an unrecognized key never reaches the error path above. It comes back as isError: true with a plain-text message naming the key:

Input validation error: Invalid arguments for tool list_items: Unrecognized key: "typ"

Branch on isError first and only parse the text when you need the structured fields. A caller that parses every error body unconditionally will throw on exactly the failure the closed inputs make most likely.

Development

git clone https://github.com/withmarfa/mcp.git
cd mcp
pnpm install
cp .env.example .env
# Edit .env with your Marfa API URL and key
pnpm build         # compiles to dist/index.js via tsup
pnpm dev           # run directly with tsx (no build step)
pnpm typecheck     # type-check without emitting
pnpm test          # run integration tests via vitest (requires a prior build)
node scripts/smoke.mjs   # end-to-end smoke against MARFA_API_URL