MCP server

deql mcp is a smaller server for trusted local agents. It communicates over stdio and uses Decisionhouse directly, while Flight SQL remains the interface for bulk Arrow data. MCP support is included in the downloaded deql release binary.

Tools

The five tools support the complete local workflow.

Tool	Purpose
`catalog`	Discover tables, columns, and candidate decision keys
`query`	Run one read-only query with bounded output
`create_candidates`	Materialize one candidate definition
`decide`	Solve a decision query
`drop_candidate`	Explicitly remove candidate state

Result limits

Query and solution results are intentionally bounded:

100 rows by default
1,000 rows at most
1 MiB maximum tool output

Use Flight SQL when a client needs complete or high-volume Arrow results.

Install DeQL

Run the installer from an interactive terminal on macOS or Linux, or from Linux under WSL on Windows:

curl -fsSL https://get.deql.osm-data.com | sh

The installer leaves you inside the directory containing ./deql and places deql-config.toml beside it. MCP registration uses the binary’s absolute path, so adding DeQL to PATH is optional. No source checkout is needed.

Let your agent connect DeQL

Replace /absolute/path/to/deql/deql with the absolute path to the installed binary. Keep the quotes if the path contains spaces. The agent starts deql mcp for you; do not run it separately.

Codex

codex mcp add deql -- "/absolute/path/to/deql/deql" mcp
codex mcp get deql

The second command confirms the saved configuration. Then start a new Codex session and run /mcp to verify that the server connected and its tools loaded.

Claude Code

claude mcp add --transport stdio deql -- \
  "/absolute/path/to/deql/deql" mcp
claude mcp get deql

Claude uses local scope by default: private to you in the current project. Add --scope user before deql to make it available in every project.

Adding DeQL to your shell’s PATH is optional. See Optional: add DeQL to PATH; MCP registration should still use the absolute binary path shown above.

Configure manually

For hosts that use the common mcpServers JSON shape, the equivalent configuration is:

{
  "mcpServers": {
    "deql": {
      "command": "/absolute/path/to/deql/deql",
      "args": ["mcp"]
    }
  }
}

Point the command at the installed binary’s absolute path and pass only mcp. The installer places deql-config.toml beside that binary, and deql mcp discovers it automatically even when the host uses another working directory.

Use --config /another/path/deql-config.toml only when you want to override the installer-created config. Custom setups can also use --connection, --candidates, and --register-files.

Candidate-set scope

Candidate state belongs to one deql mcp process and disappears when that process exits. It is not shared with a separately running Flight SQL server or another MCP process. Pass the same initialization arguments to each agent process, or use --candidates to recreate stable candidate definitions at startup.

Use Flight SQL for full results Connect Arrow-native clients without the MCP output limits.