Cursor

Cursor reads MCP servers from ~/.cursor/mcp.json (user-level) plus an optional .cursor/mcp.json per-workspace file. faz wires up the user-level config in one command.

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.
• Cursor installed (any recent version — MCP support shipped in late 2024).

Install the MCP config

faz mcp install --target cursor

uv run faz mcp install --target cursor

python -m faz mcp install --target cursor

Output:

[cursor] /Users/you/.cursor/mcp.json: written

The file is the same shape as Claude's:

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

Existing entries for other MCP servers are preserved. To preview without writing:

faz mcp install --target cursor --dry-run

uv run faz mcp install --target cursor --dry-run

python -m faz mcp install --target cursor --dry-run

User-level vs workspace-level

~/.cursor/mcp.json applies to every Cursor workspace. If you want faz available in only one project, drop the same JSON into <workspace>/.cursor/mcp.json and remove it from the user-level file. Workspace overrides win when both exist.

For most cases, user-level is the right answer — FAZ_CONFIG already pins faz to a specific faz.yaml, so per-workspace scoping happens at the config-path level rather than the MCP-registration level.

Restart Cursor

Cursor reads MCP configs at startup. Quit Cursor fully (Cmd-Q on macOS, File → Quit elsewhere) and reopen. The Cursor settings panel has an MCP section where faz should now be listed; the indicator turns green when the connection is live.

Verify

Open Cursor's chat panel and ask:

What databases do you have access to?

Cursor calls list_databases through the MCP runtime and replies with your configured databases.

For a more concrete test:

Show me the schema of the <table> table.

Cursor will call describe_table and quote the column list.

Common patterns

Cursor's strength is editor context. Combine faz queries with the editor:

• Schema-aware refactors: ask Cursor to update a query function and it'll inspect the actual table schema via describe_table before generating code.
• Inline data checks: highlight a SQL query in your editor, ask "does this return what I expect?", and Cursor runs it through faz.
• Migration drafting: ask Cursor to generate a migration; it can verify the current schema first.

The agent's writes are still gated by your permissions: block. If you have access: R and ask Cursor to run an INSERT, faz blocks at RBAC_GATE and Cursor sees a structured error explaining why.

Troubleshooting

If Cursor's MCP indicator stays red or the assistant says it can't reach faz:

• Confirm ~/.cursor/mcp.json parses as JSON: jq . ~/.cursor/mcp.json.
• Confirm command is an absolute path that exists: ls -l "$(jq -r '.mcpServers.faz.command' ~/.cursor/mcp.json)".
• Confirm FAZ_CONFIG points at a valid file: open the path from the env block, run faz policy --path /that/path/faz.yaml. If that errors, fix it before retrying Cursor.
• Restart Cursor fully.

Full diagnostic flow on MCP not loading.

Related

• Integrations overview — the cross-client comparison.
• Verifying the connection — diagnostic checks.
• MCP tools — what Cursor calls when answering data questions.