Claude Code

Claude Code is Anthropic's terminal CLI. It supports MCP servers via a per-user config file at ~/.claude.json. faz works the same as it does in Claude Desktop — same four MCP tools, same safety pipeline — but the install location is different.

For the prerequisites and the conceptual "what's MCP" answer, see Integrations overview.

Prerequisites

• faz installed (pip install faz-core — see Install).
• A faz.yaml with at least one database connection and a permissions block.
• Claude Code installed (npm install -g @anthropic-ai/claude-code).

Install the MCP config

Option 1 — Use faz mcp install (recommended)

faz mcp install --target claude-code

uv run faz mcp install --target claude-code

python -m faz mcp install --target claude-code

This writes the mcpServers.faz entry directly to ~/.claude.json. The entry looks like:

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

Confirm:

claude mcp list

You should see faz in the list.

Option 2 — Use Claude Code's mcp add

If you prefer to wire it up through Claude Code's own CLI:

claude mcp add faz -e "FAZ_CONFIG=$(pwd)/faz.yaml" -- "$(which faz)" "mcp"

This appends the same entry to ~/.claude.json under mcpServers.faz.

Restart Claude Code

Exit any active Claude Code session and start a new one. MCP servers are spawned on session start and not re-discovered mid-session.

Verify

In a new Claude Code session, ask:

What databases do you have access to?

Claude Code calls list_databases and replies with your configured databases. The shape of the reply is the same as in Claude Desktop — the underlying MCP tools are identical.

You can also confirm directly:

claude mcp list                    # should include "faz"
claude mcp get faz                 # prints the registered config

Common patterns

Claude Code is shell-context aware, so combining faz with terminal workflows works well:

• Inline schema lookup: "What columns does this table have?" mid-debugging.
• Generate and run a cross-source check: "Are there any rows in <table-1> without a matching row in <table-2>?" — Claude generates a federated query and runs it.
• Audit review: pipe faz logs --follow in another terminal alongside your Claude Code session to watch every query as it runs.

Troubleshooting

If claude mcp list doesn't show faz, or faz is listed but Claude Code can't call it:

• Confirm ~/.claude.json parses: jq . ~/.claude.json. JSON syntax errors break MCP discovery.
• Confirm the command path is the actual faz binary: which faz should match.
• Confirm FAZ_CONFIG points at a valid faz.yaml: faz policy --help from any directory followed by running with that env var.
• Restart the Claude Code session — MCP servers don't reload mid-session.

Full diagnostic flow on MCP not loading.

Related

• Integrations overview — the cross-client comparison.
• Claude Desktop — the desktop-app variant of the same wiring.
• Verifying the connection — diagnostic checks.
• MCP tools — the tools Claude Code calls.