Faz Docs

Connect any MCP-compatible client to faz — Continue, Zed, custom integrations — using the standard mcpServers JSON shape.

faz's MCP server is a standard stdio MCP server. Any client that speaks the protocol can talk to it. This page covers the wire-up for clients faz doesn't have a dedicated --target for.

For Claude Desktop, Cursor, Claude Code, and OpenClaw, see their respective pages. For the protocol and tool reference, see MCP tools.

Prerequisites

faz installed (pip install faz-core — see Install).
A faz.yaml with at least one database connection and a permissions block.
An MCP-compatible client.

The configuration faz expects clients to use

Every MCP client — at the protocol level — needs four pieces of information about each server it spawns:

The command to run.
The arguments to that command.
The environment variables to set.
(Implicit) The transport — stdio, in faz's case.

For faz, that's:

{
  "command": "/absolute/path/to/faz",
  "args": ["mcp"],
  "env": {
    "FAZ_CONFIG": "/absolute/path/to/faz.yaml"
  }
}

The container key — the JSON path under which this object lives — depends on the client.

Generate the JSON

Run faz mcp install against a fresh path so it produces a standalone file you can adapt:

faz mcp install --path /tmp/faz-mcp.json

uv run faz mcp install --path /tmp/faz-mcp.json

python -m faz mcp install --path /tmp/faz-mcp.json

You'll get a file with the standard mcpServers flat key:

/tmp/faz-mcp.json

{
  "mcpServers": {
    "faz": {
      "command": "/usr/local/bin/faz",
      "args": ["mcp"],
      "env": {
        "FAZ_CONFIG": "/Users/you/projects/myapp/faz.yaml"
      }
    }
  }
}

If your client uses a nested key (like OpenClaw's mcp.servers), pass --target openclaw:

faz mcp install --path /tmp/faz-mcp.json --target openclaw

uv run faz mcp install --path /tmp/faz-mcp.json --target openclaw

python -m faz mcp install --path /tmp/faz-mcp.json --target openclaw

Drop it into the client's config

Where this object goes depends on which MCP client you're using. Check the client's documentation for "MCP servers" or "Model Context Protocol" config. The shape will be one of:

Flat mcpServers.faz: most common (Claude, Cursor, Continue, Zed, …). Drop the inner block into the existing or new mcpServers map.
Nested mcp.servers.faz: OpenClaw and some open-source clients. Use --target openclaw so the install writes the right shape.
Per-server file: rare, but some clients want one file per server (<config-dir>/servers/faz.json or similar). Save the inner faz block to that path.

Use jq to extract just the inner block when you need to merge:

jq -c '.mcpServers.faz' /tmp/faz-mcp.json
# → {"command": "...", "args": ["mcp"], "env": {"FAZ_CONFIG": "..."}}

Restart the client

MCP clients read their server registry at startup. Restart the app for the entry to take effect.

Verify

Ask the assistant something faz answers:

What databases do you have access to?

The assistant calls list_databases and replies with your configured databases.

If you have shell access to the client's logs, look for entries indicating the MCP server spawned successfully — usually a line per registered server with the command path and a "ready" marker.

Direct testing without a client

You can confirm the faz MCP server itself works without any client by spawning it and sending JSON-RPC messages over stdin. MCP requires an initialize handshake before any other method:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | faz mcp 2>/dev/null \
  | grep '"id":2' \
  | python3 -m json.tool

A working server responds with the four tools faz exposes:

Tool	What it does
`list_databases`	Lists configured databases and their schema (paginated)
`describe_table`	Returns columns, types, and row-count estimate for one table
`query_simple`	Runs a single-database query through the 5-stage safety pipeline
`query`	Runs a multi-database federated query with optional DuckDB merge

If the command hangs or returns nothing, the problem is with faz mcp itself — confirm faz.yaml parses (faz policy) and that connectors are reachable (faz test).

Troubleshooting

If your client doesn't see faz after restart:

Wrong JSON shape: confirm the entry lives under the key your client expects. Check the client's docs.
Wrong command path: clients usually run from a sanitised PATH. Use the absolute path to faz (which faz).
FAZ_CONFIG not set or wrong: clients usually run with no working directory. Without FAZ_CONFIG, faz looks for ./faz.yaml from wherever it's spawned, which is rarely your project directory. Always set FAZ_CONFIG to an absolute path in env.
faz.yaml doesn't parse: run faz policy to confirm it loads cleanly outside MCP.

Full diagnostic flow on MCP not loading.

MCP tools — the four tools faz exposes.
Verifying the connection — diagnostic checks.
REST API — the alternative if your client doesn't speak MCP.

Generic MCP