Skip to main content
Glama

geo-query

Documentation · The bigger picture

An open Model Context Protocol (MCP) server that connects AI agents to cloud-native data: it grounds the agent in STAC metadata so it finds the right dataset and reads its schema, and confines it to validated cloud-native engines so it queries terabyte-scale data over S3 without downloading it, misreading it, or silently failing at scale. Today it serves SQL over Parquet via DuckDB with H3 spatial indexing; see the roadmap for array (Zarr) and hardware-accelerated engines.

It is one of three open-source components — with data-workflows (which produces the AI-ready data and metadata) and jupyter-geoagent — that together make the cloud-native stack reachable by the AI tools researchers already use. Runs locally for sensitive data or on autoscaling Kubernetes for scale.

Quick Start

Add the hosted MCP endpoint to your LLM client, like so. The endpoint needs a bearer token (see Authentication); ask the maintainers for one. Keep it in an environment variable or a password prompt, never in a file you commit.

The hosted endpoint duckdb-mcp.nrp-nautilus.io is offline for now: NRP has closed public access to the MCP servers on its cluster. The examples below show how a client connects once it is back.

Using VSCode

create a .vscode/mcp.json like this: (as in this repo). VS Code asks for the token once and stores it securely.

{
	"inputs": [
		{ "type": "promptString", "id": "duckdb-mcp-token",
		  "description": "Token for duckdb-mcp.nrp-nautilus.io", "password": true }
	],
	"servers": {
		"duckdb-geo": {
			"url": "https://duckdb-mcp.nrp-nautilus.io/mcp",
			"headers": { "Authorization": "Bearer ${input:duckdb-mcp-token}" }
		}
	}
}

Now simply ask your chat client a question about the datasets and it should answer by querying the database in SQL:

Examples:

  • What fraction of Australia is protected area?

alt text

Using Claude Code (CLI)

This repo's .mcp.json reads the token from the DUCKDB_MCP_TOKEN environment variable. To add the server to your own projects, export that variable and run:

claude mcp add --transport http --scope user duckdb-geo https://duckdb-mcp.nrp-nautilus.io/mcp \
  --header 'Authorization: Bearer ${DUCKDB_MCP_TOKEN}'

The single quotes keep ${DUCKDB_MCP_TOKEN} unexpanded, so the token itself is not written to your Claude Code settings.

Using Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "duckdb-geo": {
      "command": "npx",
      "args": ["mcp-remote", "https://duckdb-mcp.nrp-nautilus.io/mcp",
               "--header", "Authorization: Bearer ${DUCKDB_MCP_TOKEN}"],
      "env": { "DUCKDB_MCP_TOKEN": "<your token>" }
    }
  }
}

This file holds the token in plain text, so keep it private. After adding the configuration, restart Claude Desktop.

Related MCP server: DuckPond MCP Server

Features

  • Zero-Configuration SQL Access: Query petabytes of geospatial data without database setup

  • H3 Geospatial Indexing: Efficient spatial operations using Uber's H3 hexagonal grid system

  • Isolated Execution: Each query runs in a fresh DuckDB instance for security

  • Stateless HTTP Mode: Fully horizontally scalable for cloud deployment

  • Rich Dataset Catalog: Access to 10+ curated environmental and biodiversity datasets

  • MCP Resources & Prompts: Browse datasets and get query guidance through MCP protocol

Available Datasets

The example configuration provides access to the following datasets via S3:

  1. GLWD - Global Lakes and Wetlands Database

  2. Vulnerable Carbon - Conservation International carbon vulnerability data

  3. NCP - Nature Contributions to People biodiversity scores

  4. Countries & Regions - Global administrative boundaries (Overture Maps)

  5. WDPA - World Database on Protected Areas

  6. Ramsar Sites - Wetlands of International Importance

  7. HydroBASINS - Global watershed boundaries (levels 3-6)

  8. iNaturalist - Species occurrence range maps

  9. Corruption Index 2024 - Transparency International data

Datasets are discovered dynamically from the STAC catalog via the list_datasets and get_dataset tools.

Local Development

You can also run the server locally

Or install dependencies and run directly:

pip install -r requirements.txt
python server.py

You can now connect to the server over localhost (note http not https here), e.g. in VSCode:

{
	"servers": {
			"duckdb-geo": {
			"url": "http://localhost:8000/mcp"
		},
	}
}

You can adjust the instructions to the LLM in the corresponding .md files (e.g. query-optimization.md, h3-guide.md). You will need to adjust query-setup.md to run the server locally, as it uses endpoint and thread count that only work from inside our k8s cluster. Running locally means your local CPU+network resources will be used for the computation, which will likely be much slower than the hosted k8s endpoint.

Architecture

We have a fully-hosted version

Core Components

  • server.py - Main MCP server with FastMCP framework

  • stac.py - STAC catalog integration for dynamic dataset discovery

Runtime Prompt Files

The .md files in this repo are not documentation — they are curated prompt content loaded by server.py at startup and injected directly into MCP tool descriptions and prompts at runtime. The agent (LLM) reads them as instructions, not humans.

File

How it is used

query-setup.md

SQL parsed and executed in every fresh DuckDB connection before a query runs

query-optimization.md

Injected verbatim into the query tool description

h3-guide.md

Injected verbatim into the query tool description

assistant-role.md

Served as the geospatial-analyst MCP prompt (role + response style)

Editing these files changes what the agent is told to do. They must be written for a stateless LLM — short, concrete, and unambiguous. See AGENTS.md for editing rules.

Key Design Patterns

  1. Stateless transport: FastMCP runs in stateless streamable-HTTP mode (stateless_http=True in server.py). Every POST /mcp is a complete, independent request/response — no Mcp-Session-Id, no per-pod session cache, no in-memory state that survives across requests. Replicas behind the load balancer are interchangeable on a per-request basis. (The protocol's stateful SSE mode is not used.)

  2. Isolation Engine: Each query runs in a fresh duckdb.connect(":memory:") — no DuckDB connection, credential, or query state survives between requests

  3. Context Injection: Prompt files are embedded into tool descriptions so even MCP clients that don't support prompts/list receive the guidance

  4. Partition Pruning: H3 resolution columns (h0) enable DuckDB to skip S3 partitions, giving 5–20× speedups on large datasets

Kubernetes Deployment

Deploy to Kubernetes using the provided manifests:

kubectl apply -f k8s/mcp-egress-networkpolicy.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

Don't apply k8s/ingress.yaml or k8s/dev-ingress.yaml while NRP keeps public access to the MCP servers closed; NRP removed those Ingresses and will say when they can return.

The egress policy limits the servers to cluster DNS and https to public addresses, so they read NRP Ceph through its external endpoint (S3_DEFAULT_ENDPOINT in the manifests). Apply it before a Deployment that reads Ceph that way. NRP also blocks pod traffic between namespaces, so a server is reachable in-cluster only from its own namespace; see Authentication.

The deployment:

  • Runs multiple replicas for high availability (prod: 6, dev: 2)

  • Allocates up to 160 Gi memory / 16 CPU per pod for large queries

  • Bakes the application code and dependencies into the image (no runtime clone)

  • Guards spill disk pod-wide. Each query spills to its own directory, and a watchdog measures them all against the pod's ephemeral-storage limit (POD_EPHEMERAL_LIMIT). At half the limit (SPILL_DRAIN_FRACTION) the pod fails /readyz and turns new queries away with a retry message, so they go to other replicas. At 80% (SPILL_INTERRUPT_FRACTION) it interrupts the newest query that has spilled at least 1 GiB (SPILL_MIN_VICTIM), which fails with an error rather than the kubelet evicting the pod. Older queries have done the most work and keep running; if stopping the newest does not free enough, the next check stops the next newest, and only when no spill is that big does it take the largest. It checks every second (SPILL_GUARD_INTERVAL).

  • Guards memory the same way, since DuckDB's memory_limit is also per query. It drains the pod at half its memory limit (MEMORY_DRAIN_FRACTION), and at 90% (MEMORY_INTERRUPT_FRACTION) interrupts the newest query holding at least 1 GiB (MEMORY_MIN_VICTIM), chosen as for disk, before the OOM killer stops the whole pod. It also watches the node: while the pod holds 8 GiB or more (NODE_MEMORY_MIN_POD), it drains when the node has less than 16 GiB available (NODE_MEMORY_DRAIN_FLOOR) and interrupts below 8 GiB (NODE_MEMORY_INTERRUPT_FLOOR), because the pod's 2 Gi request does not reserve what a heavy query uses. Memory is read every 0.25 s (MEMORY_GUARD_INTERVAL), and a query is stopped early when memory would cross the mark within the next second at its current rate of growth (MEMORY_LOOKAHEAD). Draining follows what the pod actually holds, including memory a stopped query is still releasing. Because DuckDB can take many seconds to release a stopped query's memory, the guard also stops the next newest query if the pod passes 95% of its limit (MEMORY_HARD_FRACTION) and is still rising. MEMORY_GUARD=0 turns this off.

  • Includes /healthz (liveness) and /readyz (readiness) probes for safe rollouts. /readyz also fails while the pod has no STAC catalog, so a pod that booted with STAC_ALLOW_DEGRADED_START leaves the Service until its catalog loads; set STAC_READY_WITHOUT_CATALOG=true to keep such a pod in service.

Releases and production rollouts

Application code is baked into the image (COPY . /app in the Dockerfile); pods no longer git clone at startup. CI (.github/workflows/docker.yml) builds on every push to main and on vX.Y.Z tags:

  • dev pins the moving :main tag (imagePullPolicy: Always) and tracks the latest main.

  • prod pins an immutable vX.Y.Z@sha256:<digest> (imagePullPolicy: IfNotPresent) — every replica is identical by construction.

The convention is every release tag is a GitHub Release — when you cut a version, push the tag (CI builds :vX.Y.Z), publish a release with notes (gh release create vX.Y.Z --generate-notes), then pin prod to that build's digest. The full step-by-step (including reading the digest) lives in AGENTS.md → Rollout workflow. The latest GitHub Release is the source of truth for "what should be running in prod."

To confirm prod is on the intended release:

# Digest the prod manifest pins:
kubectl -n biodiversity get deploy duckdb-mcp \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

# Every running pod should report that same digest:
kubectl -n biodiversity get pods -l app=duckdb-mcp \
  -o custom-columns=NAME:.metadata.name,IMAGE:.status.containerStatuses[0].imageID

If every pod's imageID matches the pinned digest, prod is current and consistent.

MCP Protocol Features

Tools

  • browse_stac_catalog(catalog?) - List available datasets from the deployment's STAC catalog (registered only when discovery is enabled; see STAC_DISCOVERY)

  • get_stac_details(dataset_id, collection?) - Get S3 paths and schema for a dataset

  • query(sql_query, s3_endpoint?, s3_scope?, s3_region?, s3_url_style?) - Execute DuckDB SQL against S3 parquet files. It also accepts s3_key and s3_secret from a server-side proxy, but does not offer them to the model (see Private S3 data).

Resources

NOTE: Some MCP clients, like in VSCode, do not recognize "resources" and "prompts". Newer clients (Claude code, Continue.dev, Antigravity do)

  • catalog://list - List all available datasets

  • catalog://{name} - Get detailed schema for a specific dataset

Prompts

  • geospatial-analyst - Load complete context for geospatial analysis persona

Query Optimization Tips

  1. Always include h0 in joins - Enables partition pruning for 5-20x speedup

  2. Compute areas with SUM(h3_cell_area(h8, 'km^2')) - Exact per-cell area over distinct cells (H3 cells are not equal-area)

  3. Filter small tables first - Create CTEs to reduce join cardinality

  4. Set THREADS=100 - Parallel S3 reads are I/O bound, not CPU bound

  5. Enable object cache - Reduces redundant S3 requests

See query-optimization.md for detailed guidance.

H3 Spatial Operations

All datasets use Uber's H3 hexagonal grid system for spatial indexing:

  • Resolution 8 (h8): ~0.74 km² per hex (nominal; true cell area varies ~0.55–0.82 km²)

  • Resolution 0-4 (h0-h4): Coarser resolutions for global analysis

  • Use h3_cell_to_parent() to join datasets at different resolutions

  • Compute areas with SUM(h3_cell_area(h8, 'km^2')) over distinct cells — exact at any resolution. Multiplying a hex count by a nominal per-cell constant is a global-average approximation only, suitable for unscoped global aggregates. See h3-guide.md.

Testing

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_server.py

# Run with coverage
pytest --cov=. tests/

Configuration

Environment Variables

  • THREADS - DuckDB thread count (default: 100 for S3 workloads)

  • PORT - HTTP server port (default: 8000)

  • MCP_AUTH_TOKENS_DIR - directory of bearer tokens, one file per caller, named for it (see Authentication)

  • MCP_AUTH_TOKEN - a single bearer token, named default; older deployments use this

  • MCP_AUTH_PUBLIC_TILES - true serves GET /tiles/... without a token (default: off)

  • MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS - turn on DNS-rebinding protection for /mcp, comma-separated (see Running on localhost)

  • S3_ALLOWED_ENDPOINTS - extra hosts accepted as the query tool's s3_endpoint, comma-separated

  • TILE_BUCKET_BASE - where register_hex_tiles writes tile pyramids (default: s3://public-output)

  • TILE_WRITE_KEY_ID, TILE_WRITE_SECRET - a key that writes only the tile bucket, for private replicas (see Private hex tiles); TILE_WRITE_ENDPOINT and TILE_WRITE_USE_SSL set its endpoint when it is not the default one

DuckDB Settings

Required settings are documented in query-setup.md and automatically injected into query tool descriptions.

Private Data Access

The server supports private STAC catalogs and private S3 buckets. Query credentials are supplied per-call by the client and are scoped to that request only — they are never logged, cached, or shared between clients. Catalog scope is not: which catalog this server reads is a property of the deployment.

Private STAC catalog

Point the deployment at its own catalog and give it the bearer token in the environment:

env:
  - name: STAC_CATALOG_URL
    value: https://your-app.example.org/stac/catalog.json
  - name: STAC_CATALOG_TOKEN
    valueFrom:
      secretKeyRef: { name: stac-catalog, key: token }

The token is forwarded as Authorization: Bearer <token> when fetching catalog JSON, and never appears in a JSON-RPC body. The tools take no catalog_url / catalog_token arguments — an app's data universe is configured once, not re-decided by the model on every call (#420). A client that already holds the STAC JSON can still pass it inline as collection / catalog to skip the fetch.

Serving a private catalog: The catalog endpoint needs to accept bearer token authentication for machine-to-machine access. If you are using oauth2-proxy for human (browser) access, add a parallel nginx auth_request bypass for the /stac/ path that accepts a static shared token via the Authorization header. This allows the MCP server to fetch catalog metadata without requiring a browser OAuth session.

Private S3 data

Credentials never come from the model. The model writes every tool argument, so a key it passed would also sit in the conversation sent to the language model. s3_key and s3_secret are therefore left out of the query schema and description the model sees, and the server still accepts them from a proxy between the app and the server. In a private app, a server-side proxy injects the deployment's keys into tools/call for SQL that names its private bucket (tpl-internal's mcp-credential-proxy), or a private replica reads the bucket with credentials from its own S3_SOURCES. Users who bring their own keys to their own bucket can enter them in the browser with geo-query-wasm, which also keeps them from the model.

The server makes the injected keys a DuckDB secret for that query only, then destroys the connection. A call with keys, as the proxy sends it:

{ "tool": "query", "arguments": {
    "sql_query": "SELECT * FROM read_parquet('s3://my-private-bucket/data/**') LIMIT 10",
    "s3_key": "YOUR_ACCESS_KEY_ID",
    "s3_secret": "YOUR_SECRET_ACCESS_KEY",
    "s3_endpoint": "minio.example.org"
}}

s3_endpoint defaults to s3-west.nrp-nautilus.io if omitted. SSL is enabled automatically for non-Ceph endpoints.

Security properties

Concern

How it is handled

Keys reaching the model

s3_key and s3_secret are not in the schema or description the model sees. The SQL cannot call duckdb_secrets() or which_secret(), which would show the key ID. Key values are replaced by [REDACTED] in results and error text.

Credential bleed between clients

Each request uses a separate duckdb.connect(":memory:") — DuckDB secrets are connection-scoped and destroyed on close

Credentials in server logs

CREATE SECRET statements are constructed internally and never written to stderr

Credentials in transit

All traffic is TLS-terminated at the ingress

Credential persistence

stateless_http=True — no session state survives between requests

Private hex tiles

On the public servers, hex tiles go to s3://public-output, which accepts anonymous writes, and caller SQL may also write there (csv exports). A private replica writes its tiles to a private bucket instead, which needs a key with write access. To keep that key away from caller SQL, give the replica two keys:

  • a read-only key in S3_SOURCES, used by query, by tile serving and by the source side of a tile build;

  • a key that can list, read and write only the tile bucket, in TILE_WRITE_KEY_ID and TILE_WRITE_SECRET, with TILE_BUCKET_BASE set to that bucket.

With a write key set, a tile build uses two connections. One runs the caller's SQL with read credentials and aggregates it to the finest resolution. The result streams in Arrow batches to the other, which holds only the write key and never runs caller SQL; it writes that level, builds the coarser ones from the bucket, and writes the metadata and the build's lock and failure markers. Without a write key, builds run on one connection as they always have.

Deploying private apps without a separate server

Rather than maintaining a forked server deployment per app, private geo-agent apps can share the public MCP server endpoint, with a server-side proxy adding their credentials to each call. This reduces idle deployments and ensures all apps benefit from server improvements automatically. Like every app, they still need a bearer token for the endpoint, held server-side (see Authentication).

Security

  • Stateless Design: No persistent database or user data

  • Query Isolation: Each request gets a fresh DuckDB instance; client credentials cannot bleed across requests

  • DNS Rebinding Protection: Disabled for MCP HTTP mode

Authentication

Every route except /healthz, /readyz and /version needs Authorization: Bearer <token>. Deployments that set MCP_AUTH_PUBLIC_TILES=true also serve GET /tiles/... without a token, since the tile pyramids sit in a public bucket and browsers fetch them directly. Private replicas leave it off.

Each caller has its own named token, in practice one per Kubernetes namespace of apps. The server reads every file in MCP_AUTH_TOKENS_DIR as a token named after the file. That is the layout of a Secret mounted as a volume, so on NRP the tokens live in the duckdb-mcp-tokens Secret in biodiversity, mounted at /etc/mcp-tokens. The query log shows the caller's name, never the token (🔍 Executing [schmidtdse]: …). Apps that share a key send an X-Glen-App header with their name, which the log adds ([public/padus]). The header only labels the log line; access depends on the key alone, and a value that isn't a plain app name is logged as ?. If MCP_AUTH_TOKENS_DIR is set but yields no tokens, the server refuses to start rather than start without auth.

Apps keep their token server-side: their nginx proxies a same-origin /api/mcp to the server and adds the header, so the token never reaches a browser.

To add or revoke a token, edit the Secret, then restart the deployments, because tokens are read at startup:

# add: generates the token without printing it
kubectl -n biodiversity get secret duckdb-mcp-tokens -o json \
  | python3 -c 'import sys,json,base64,secrets; s=json.load(sys.stdin); s["data"]["<name>"]=base64.b64encode(secrets.token_urlsafe(32).encode()).decode(); [s["metadata"].pop(k,None) for k in ("resourceVersion","uid","creationTimestamp","managedFields")]; print(json.dumps(s))' \
  | kubectl apply -f -
# revoke
kubectl -n biodiversity patch secret duckdb-mcp-tokens --type=json -p '[{"op":"remove","path":"/data/<name>"}]'
# either way
kubectl -n biodiversity rollout restart deployment/duckdb-mcp deployment/dev-duckdb-mcp

Apps reach the server in-cluster, from its own namespace. NRP blocks pod traffic between namespaces, so an app in another namespace cannot call the biodiversity server's Service; the request times out. Such an app uses a server in its own namespace, as the schmidtdse apps do (next section), or the public endpoint when there is one. An app that calls the public endpoint keeps its token in a Secret duckdb-mcp-auth, key MCP_AUTH_TOKEN, in its own namespace.

Running on localhost

A server on someone's own machine should check the Host and Origin of each request. Without the check, a web page can re-point its own hostname at 127.0.0.1 (DNS rebinding), and the browser will then let it call the local server and read the results. Setting MCP_ALLOWED_HOSTS turns the check on for /mcp: a request whose Host is not listed gets 421, and a request from a browser page whose Origin is not listed gets 403. Clients that send no Origin, such as scripts and the headless runner, pass. host:* matches any port. For a server behind an nginx on port 8080 that forwards Host $host:

MCP_ALLOWED_HOSTS=localhost,127.0.0.1
MCP_ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080

With neither variable set the check is off, as the public deployments need: they are reached from any origin, under hostnames the ingress picks. Setting only MCP_ALLOWED_ORIGINS stops the server at startup, because with no allowed hosts every request would be refused.

The schmidtdse server

The schmidtdse namespace runs its own copy of the server (k8s/schmidtdse-*.yaml) with its own tokens. The apps listed in the duckdb-mcp-containment NetworkPolicy reach it in-cluster, at http://duckdb-mcp.schmidtdse.svc.cluster.local:8000. Tiles are not public there, so browsers fetch them through each app, which adds its token.

Headless callers outside the cluster, such as CI, use https://geo-query.nrp-nautilus.io/mcp with a key of their own in duckdb-mcp-tokens (k8s/schmidtdse-ingress.yaml). That route serves only /mcp and /version, with no CORS and a per-IP rate limit. It does not serve /tiles/, so register_hex_tiles URLs are not usable from it.

Tokens live in the Secret schmidtdse/duckdb-mcp-tokens, one key per app, named for the app. The same Secret is mounted into the server as MCP_AUTH_TOKENS_DIR and referenced by each app's Deployment:

- name: MCP_AUTH_TOKEN
  valueFrom:
    secretKeyRef: {name: duckdb-mcp-tokens, key: <app>}

The server returns hex tile URLs on its MCP_PUBLIC_BASE_URL, which is the internal address above. Each app's nginx rewrites that prefix to its own host in /api/mcp responses and proxies /tiles/ to the server:

location /api/mcp {
    proxy_pass http://duckdb-mcp.schmidtdse.svc.cluster.local:8000/mcp;
    proxy_http_version 1.1;
    proxy_set_header Host duckdb-mcp.schmidtdse.svc.cluster.local;
    proxy_set_header Connection "";
    proxy_set_header Authorization "Bearer ${MCP_AUTH_TOKEN}";
    # sub_filter cannot read a gzipped body.
    proxy_set_header Accept-Encoding "";
    sub_filter 'http://duckdb-mcp.schmidtdse.svc.cluster.local:8000/tiles/' 'https://$host/tiles/';
    sub_filter_once off;
    sub_filter_types text/event-stream application/json;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    proxy_buffering off;
}

location /tiles/ {
    limit_except GET { deny all; }
    proxy_pass http://duckdb-mcp.schmidtdse.svc.cluster.local:8000/tiles/;
    proxy_http_version 1.1;
    proxy_set_header Host duckdb-mcp.schmidtdse.svc.cluster.local;
    proxy_set_header Connection "";
    proxy_set_header Authorization "Bearer ${MCP_AUTH_TOKEN}";
}
  • MCP_PUBLIC_BASE_URL must stay exactly http://duckdb-mcp.schmidtdse.svc.cluster.local:8000, since every app's sub_filter matches it. An empty value gives relative URLs that the rewrite misses.

  • An app that already serves something else at /tiles/ can rewrite and proxy a narrower prefix. cacao-internal uses /tiles/hex/, because its /tiles/ serves private PMTiles.

  • Behind oauth2-proxy, $host is still the app's public host, since oauth2-proxy passes Host through.

  • To add an app, add its app label to the ingress list in k8s/schmidtdse-networkpolicy.yaml and apply it, add a key for it to duckdb-mcp-tokens (the add command above, with -n schmidtdse), and restart deployment/duckdb-mcp in schmidtdse so the server reads the new token.

The server's egress is limited to cluster DNS and https to public addresses, so it reads NRP Ceph through the external endpoint s3-west.nrp-nautilus.io.

Local file access and DuckDB settings

Queries can read remote data but not the server's own disk, and cannot change how DuckDB is configured. Every connection that runs caller SQL (the query tool, and the tile connections behind register_hex_tiles) is set up by the server and then locked with DuckDB's own settings (dbconfig.lock_down()):

  • allowed_directories admits s3://, https:// and the connection's own spill directory under /tmp, then enable_external_access=false turns everything else off. Local reads and writes, glob, ATTACH, INSTALL and plain http:// paths are refused. s3:// paths still reach NRP Ceph's internal endpoint over http, because the S3 secret, not the path, picks the endpoint.

  • Extension autoload, autoinstall and community extensions are off, so no extension code runs beyond what the server loaded.

  • lock_configuration=true comes last: SET, RESET and PRAGMA all fail, so caller SQL can neither undo the lock nor change memory_limit or any other setting. The server applies every setting itself; SQL needs no setup lines.

  • Persistent secrets are off, so DuckDB never opens ~/.duckdb/stored_secrets.

  • The query tool's s3_endpoint must be a known S3 host (NRP Ceph, the lab MinIO, registry sources, AWS S3, or S3_ALLOWED_ENDPOINTS), since it decides where s3:// reads go.

  • Tile names in /tiles/... URLs must be 16-hex content hashes before they reach any SQL.

Pods also run with automountServiceAccountToken: false, since the server never calls the Kubernetes API.

License

BSD-3-Clause License — see LICENSE.

Contributing

Contributions welcome! Key areas:

  • Additional dataset integrations

  • Query optimization patterns

  • STAC catalog enhancements

  • Documentation improvements

References

Support

For issues and questions:

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      An Iceberg-native geospatial MCP server powered by DuckDB that provides tools for spatial SQL queries, catalog discovery, and data management. It enables LLM agents to interact with Apache Iceberg lakehouses to perform complex spatial analysis, joins, and aggregations.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides AI agents with geospatial analytics by querying Overture Maps data directly from S3, enabling place analytics, building composition, land use classification, and transportation analysis.
      13
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for spatial queries via the Terranode Geospatial API, enabling AI agents to perform point-in-polygon lookups, nearest feature search, distance calculations, and spatial joins.
      6
      48 npm
      MIT