MCP Not Loading

You ran faz mcp install, restarted your AI client, and the assistant says it has no databases — or doesn't know what faz is at all. This page walks through the diagnostic flow.

For verifying a connection that should work, see Verifying the connection.

First: confirm faz mcp itself works

Before blaming the client, confirm faz mcp starts cleanly. Run it manually and feed it a basic JSON-RPC request:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | faz mcp 2>&1 | head -20

You should see a JSON response listing the four tools (list_databases, describe_table, query_simple, query). If you see a Python traceback or no faz.yaml or database.yaml, the problem is upstream of MCP entirely — fix the faz.yaml lookup first:

faz policy        # confirm faz.yaml parses
FAZ_CONFIG=/absolute/path/to/faz.yaml faz mcp

Once faz mcp runs cleanly under the same env vars your client will use, move on.

Claude Desktop doesn't see faz

The config file isn't where Claude expects

Claude Desktop reads:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Confirm the file exists and has an mcpServers.faz block:

jq '.mcpServers.faz' "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

If null, re-run faz mcp install --target claude.

The command path is wrong

The command field is the absolute path to the faz binary. Spawning Claude Desktop runs with a sanitised PATH that often doesn't include /usr/local/bin or your venv. Check:

jq -r '.mcpServers.faz.command' ~/Library/Application\ Support/Claude/claude_desktop_config.json

That path must exist and be executable. If it doesn't (you've moved your venv, switched Python versions, etc.), re-run faz mcp install --target claude from the directory where faz is on your current PATH.

FAZ_CONFIG points at a path that doesn't exist

Same issue, different field. The env.FAZ_CONFIG value is baked at install time:

jq -r '.mcpServers.faz.env.FAZ_CONFIG' ~/Library/Application\ Support/Claude/claude_desktop_config.json

Confirm the file exists and parses (faz policy --path /that/path/faz.yaml).

You restarted the window, not the app

Claude Desktop only re-reads the MCP config when the app starts. Closing the window doesn't quit the app. Cmd-Q on macOS, File → Quit elsewhere.

Inspect Claude's MCP logs

Claude Desktop writes a per-server MCP log:

• macOS: ~/Library/Logs/Claude/mcp-server-faz.log
• Linux: ~/.config/Claude/logs/mcp-server-faz.log
• Windows: %APPDATA%\Claude\logs\mcp-server-faz.log

The file shows what faz mcp printed at startup. Common findings:

• Python tracebacks — faz.yaml is broken or the connectors crashed.
• Permission denied — the command path isn't executable for the user Claude runs as.
• No log file at all — Claude never tried to spawn faz; the JSON config didn't parse.

Cursor doesn't see faz

Config in the wrong location

Cursor reads ~/.cursor/mcp.json. There's also a per-workspace .cursor/mcp.json that overrides for one project. Confirm:

jq '.mcpServers.faz' ~/.cursor/mcp.json

If a workspace override exists, it might be missing faz even though the user-level file has it.

MCP indicator stays red

In Cursor's MCP settings panel, each registered server has an indicator. Red means the spawn failed. Cursor logs MCP output to its standard log location (Help → Show Logs); look for lines mentioning faz.

Workspace path issues

If you set FAZ_CONFIG to a path relative to your user home (~/projects/myapp/faz.yaml), Cursor's workspace might run from a different directory. Always use absolute paths in FAZ_CONFIG.

Claude Code doesn't see faz

claude mcp list doesn't include faz

Either faz was never registered, or ~/.claude.json isn't parseable. Check:

jq . ~/.claude.json | head -30

If the JSON is broken, fix it manually or re-add via claude mcp add faz --command "$(which faz)" --args "mcp" --env "FAZ_CONFIG=$(pwd)/faz.yaml".

Session ran before registering

MCP servers are spawned at session start. Exit any running Claude Code session and start fresh.

OpenClaw doesn't see faz

openclaw mcp list doesn't include faz

Either the entry isn't in ~/.openclaw/openclaw.json, or it's at the wrong nesting (OpenClaw uses mcp.servers, not the flat mcpServers). Check:

jq '.mcp.servers.faz' ~/.openclaw/openclaw.json

If null, re-run faz mcp install --target openclaw (which uses the right nesting), or use OpenClaw's mcp set (see OpenClaw integration).

Restart didn't pick up the change

OpenClaw reads its config on startup. Restart the app fully.

Generic MCP clients

For clients faz doesn't have a --target for, the troubleshooting matrix is:

1. JSON shape: confirm the entry lives under the key the client expects. Most use flat mcpServers; OpenClaw uses nested mcp.servers. Check the client's docs.
2. Path: confirm command is absolute and executable.
3. Env: confirm FAZ_CONFIG is set to an absolute path. Without it, faz mcp looks for ./faz.yaml from the client's working directory, which is rarely your project directory.
4. Logs: every MCP client logs server spawn output somewhere — find it in the client's docs.

See Generic MCP for the install pattern.

faz mcp itself fails to start

If your AI client is correctly configured but faz mcp crashes when spawned:

no faz.yaml or database.yaml

FAZ_CONFIG either isn't set in the client's env block, or points at a path that doesn't exist. Set it explicitly:

"env": {
  "FAZ_CONFIG": "/absolute/path/to/faz.yaml"
}

Connector startup tracebacks

A failing connector at startup logs a WARNING and continues — faz boots without that database. But if every connector fails (e.g. Postgres process down), the MCP client sees an empty database list.

Confirm faz test works from the same shell with the same FAZ_CONFIG. If it does and the MCP client doesn't, the client's environment differs (PATH, working directory, env vars).

"I don't have access to any databases"

The assistant connected to faz, but list_databases returned an empty list. Causes:

• Every connection failed at startup. Check faz's logs for connector errors.
• faz.yaml has no databases: entries. Run faz policy to confirm what's loaded; run faz add-database to add one.
• FAZ_CONFIG points at a different file than you edited. Confirm the path matches.

Related

• Integrations overview — per-client wire-up.
• Verifying the connection — diagnostic checks for a working setup.
• Connection failed — fixes for the per-database errors that show up in MCP logs.
• Common errors — the broader error index.