fastgeoapi

OGC APIs on top of cloud-native geospatial formats. Your data is already GeoParquet, PMTiles or COG in a bucket, and something still needs a standard API in front of it: QGIS, a browser, a partner, an agent. fastgeoapi serves one straight from those formats, where they are — no load into a database, no pre-cut tile tree, no second copy to keep in step — with pygeoapi as the engine.

Serving a cloud-native format means reading it in ranges over the network, so the request path is async-first: those reads are awaited together rather than parking a thread each. Authentication, authorization and an MCP endpoint for AI agents come with it 🗺️🔒.

    

What fastgeoapi adds to pygeoapi

fastgeoapi is not a fork: pygeoapi is the engine, and fastgeoapi tracks its releases. Everything you can serve with pygeoapi you can serve here, with the same responses. What changes is which formats can be a collection without being converted first, how the server reaches them, and what stands in front.

Three numbers from the measurements behind those rows: a bbox query on Overture's division-areas (4.47 GB, read from Europe) went from 44 s to 0.9 s once warm; twenty vector tiles that take 8–11 s one at a time come back in 1.7–2.6 s with eight awaited together, on a single vCPU; and reusing provider instances took HTTP latency from 73 ms to 24 ms.

👉 What fastgeoapi adds to pygeoapi explains each row, with links to the how-to guides.

Architecture

This diagram gives an overview of the basic architecture:

Features

🧊 Cloud-Native Geospatial, served as an OGC API

• GeoParquet collections, queried in place - DuckDB with the spatial extension reads the file where it sits; bbox, datetime, property filters and full CQL2 (text and JSON, spatial predicates included) become SQL pushed into the engine, so the network carries the answer and not the dataset
• PMTiles archives as a tile collection - one file of any size, read by byte range: Overture's 18 GB places.pmtiles is a collection with no copy on the server, and a tile costs one ranged read once its directory is cached
• Any object store, one code path - S3, GCS, Azure, Tigris, MinIO or a local path, with per-dataset region, endpoint and anonymous access; the configuration document itself can live in the same bucket
• No ETL step in the middle - nothing is loaded into a database or pre-cut into a tile tree, so there is no second copy to keep in step with the first
• Cloud Optimized GeoTIFF, worked end to end - the provider pattern applied to a real COG with async-geotiff, in the contributor guide, for the format we do not ship a provider for
• Locality measured, not assumed - same-region and cross-region numbers are published, so staging an extract is a decision with figures behind it

⚡ Async-first, where waiting is the cost

• One awaited route - tile data is served on the event loop when the provider says it can be; everything else keeps pygeoapi's behaviour byte for byte
• A pattern, not a fork - AsyncProviderMixin gives a provider a second face beside its synchronous one, which pygeoapi's own chain goes on using
• Sans-I/O cores - reading an archive is written as a generator that asks for byte ranges; a blocking driver and an awaiting driver feed the same code, so one implementation serves both faces
• A storage layer that speaks ranges - with single-flight de-duplication: a cold burst of fifty tiles went from 245 ranged reads to 54
• A guard in the test suite - blockbuster fails any test that blocks the loop, so async stays a property of the code rather than an intention
• Honest about where it does not apply - DuckDB scanning GeoParquet is CPU-bound work, so it is dispatched to a thread; awaiting it would change the syntax and nothing else

🔐 Security & Authentication

• OpenID Connect (OIDC) Integration - OAuth2/JWT Bearer token authentication with JWKS support
• API Key Authentication - Flexible API key-based authentication for programmatic access
• Open Policy Agent (OPA) - Policy-based authorization with fine-grained access control
• Multi-scheme Support - Seamlessly switch between authentication methods based on your needs

🤖 AI Agents (MCP)

• Integrated MCP Server - Your OGC API exposed as Model Context Protocol tools, generated from the OpenAPI document — a new collection becomes callable with no tool definition to write
• In-process, not a second API - MCP reaches pygeoapi over an ASGI transport: no network hop, no internal API key
• Own OAuth Authorization Server - An OIDC proxy fronting any IdP: PKCE, Dynamic Client Registration (RFC 7591), Protected Resource Metadata (RFC 9728), refresh-token rotation
• CIMD & enterprise identity - Client ID Metadata Document exercised in production by Claude; EMA/ID-JAG under verification
• Stateless transport - Restarts, redeploys and autosuspend are transparent to connected clients

⚙️ Configuration You Can Change Safely

• Configuration editor - fastgeoapi config edit opens a local editor for the pygeoapi document, on loopback only
• Two views, one document - a schema-driven form and a YAML editor; the form never overwrites keys the schema does not describe
• Dry run before saving - builds the whole API from your candidate configuration and reads one item per collection, so a broken source is found before it is served
• Writing is not activating - the editor mounts no reload webhook: putting a configuration into service stays a separate, deliberate gesture
• JSON endpoints too - the same checks run from curl or in CI, with no browser involved

🧰 The stack underneath

• FastAPI and Starlette - the ASGI application pygeoapi is mounted into, built programmatically rather than at import time
• Modern Python - 3.12+, typed throughout, checked with ty in CI
• uv - one lockfile for the application, the tools and the container image

🗺️ Geospatial API Standards

• OGC API Compliance - Features, Tiles, Processes, Records, EDR and STAC, from pygeoapi unchanged
• Only what you configured - the route table and /conformance are built from your resources, so they describe what this server can really do
• OpenAPI Integration - auto-generated, with the security schemes of the chain you configured and external $refs resolved deterministically
• Standards on top of cloud-native data - the same conformance classes whether a collection is a local GeoJSON file or a 18 GB PMTiles archive in a bucket

🛡️ Security Testing & Quality

• Contract Testing - Automated OpenAPI contract validation with Schemathesis
• Security Scanning - OWASP ZAP integration for continuous security testing
• Pre-commit Hooks - Code quality checks with Ruff formatting and linting
• Comprehensive Test Coverage - Full test suite with pytest and coverage reporting

📋 OGC API Conformance

• Specification Validation - Automated validation against OGC API standards using ogcapi-registry
• OpenAPI Document Verification - Ensures generated OpenAPI documents conform to OGC API specifications
• Conformance Class Reporting - Detailed reports on declared conformance classes (OGC API - Features, Common, GeoJSON, etc.)
• CI/CD Integration - Continuous validation on every deployment to the demo server

Live Demo

A public demo server is available at https://fastgeoapi.fly.dev/geoapi.

🔐 The API endpoints are protected with OAuth2 client-credentials flow, showcasing fastgeoapi's enterprise-ready security features. This allows you to test the full authentication workflow in a real environment.

The Swagger UI documentation is publicly accessible without authentication at https://fastgeoapi.fly.dev/geoapi/openapi, allowing you to explore the API specification and available endpoints before authenticating.

Getting an Access Token

The demo server requires OAuth2 authentication. To obtain an access token:

curl -X POST https://76hxgq.logto.app/oidc/token \
  -H "Authorization: Basic czRyZjIzbnlucmNvdGM4NnhuaWVxOlc2RHJhQWJ1MTZnb29yR0xWSE02WFlSUnI4aWpObUww" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&resource=https://fastgeoapi.fly.dev/geoapi/&scope=openid profile ci"

Using the Access Token

Once you have the token, include it in your requests:

# Get the landing page
curl -H "Authorization: Bearer <your_access_token>" \
  "https://fastgeoapi.fly.dev/geoapi/?f=json"

# List collections
curl -H "Authorization: Bearer <your_access_token>" \
  "https://fastgeoapi.fly.dev/geoapi/collections?f=json"

# Check conformance
curl -H "Authorization: Bearer <your_access_token>" \
  "https://fastgeoapi.fly.dev/geoapi/conformance?f=json"

Requirements

• pygeoapi
• fastapi-opa
• An OpenID Connect provider (Keycloak, WSO2, etc)
• Open Policy Agent (OPA)

Installation

You can install fastgeoapi via pip from PyPI:

pip install fastgeoapi

Development

Prerequisites

Install UV - a fast Python package installer and resolver:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup

After cloning the repository, use UV to install dependencies:

git clone https://github.com/geobeyond/fastgeoapi.git
cd fastgeoapi
uv sync

This automatically:

• Creates a virtual environment in .venv
• Installs all required dependencies including git-based packages from [tool.uv.sources] (pygeoapi master, pygeofilter)
• Sets up fastgeoapi in development mode

Note: For development, UV uses git-based dependencies defined in [tool.uv.sources] to get the latest features from upstream projects. The PyPI release uses stable published versions. See uv.md for more details.

Activate the Virtual Environment

macOS / Linux:

source .venv/bin/activate

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Running fastgeoapi

Once Keycloak and OPA have been started, configure the required environment variables:

export PYGEOAPI_CONFIG=pygeoapi-config.yml
export PYGEOAPI_OPENAPI=pygeoapi-openapi.yml
export FASTGEOAPI_CONTEXT='/geoapi'

Start fastgeoapi in development mode:

uv run fastapi run app/main.py --app app --host 0.0.0.0 --port 5000 --reload

Quick Start (Package Installation)

Install fastgeoapi:

pip install fastgeoapi

Create a .env file with the required configuration:

# Environment state: 'dev' or 'prod'
ENV_STATE=dev

# Server configuration
HOST=0.0.0.0
PORT=5000

# Logging (required)
DEV_LOG_PATH=/tmp
DEV_LOG_FILENAME=fastgeoapi.log
DEV_LOG_LEVEL=debug
DEV_LOG_ENQUEUE=true
DEV_LOG_ROTATION=1 days
DEV_LOG_RETENTION=1 months

# Pygeoapi configuration
DEV_PYGEOAPI_BASEURL=http://localhost:5000
DEV_PYGEOAPI_CONFIG=pygeoapi-config.yml
DEV_PYGEOAPI_OPENAPI=pygeoapi-openapi.yml
DEV_FASTGEOAPI_CONTEXT=/geoapi

# Authentication (choose one, all others must be false)
DEV_API_KEY_ENABLED=false
DEV_JWKS_ENABLED=false
DEV_OPA_ENABLED=false

Start the server:

fastgeoapi run

With options:

fastgeoapi run --host 0.0.0.0 --port 5000 --reload

Edit the configuration, with a form and a YAML view side by side:

fastgeoapi config edit
fastgeoapi config edit --source s3://my-bucket/pygeoapi-config.yml

It prints a per-run token and an address to open. It stays on loopback, and it can write a configuration but never put one into service — see the command line and editing the configuration.

See the Getting Started guide for complete setup instructions including authentication options and examples.

Common UV Commands

# Update dependencies
uv sync --upgrade

# View installed packages
uv pip list

# Install a new package
uv pip install package-name

# Install dev dependencies
uv pip install --group dev

For more details, see uv.md.

Release Workflow

This project uses a branching strategy with automated releases:

Development Releases

Push to develop branch triggers automatic publishing to TestPyPI:

git checkout develop
# Make changes
git commit -m "feat: add new feature"
git push origin develop

The workflow automatically creates a dev version (e.g., 0.0.4.dev.1733912345) and publishes to TestPyPI.

Production Releases

To create a production release on PyPI:

1. Update the version in pyproject.toml
2. Merge to main branch
3. The workflow detects the version change, creates a git tag, and publishes to PyPI

# Update version in pyproject.toml to e.g., 0.0.4
git checkout main
git merge develop
git push origin main

Both workflows use Trusted Publisher (OIDC) for secure, tokenless authentication with PyPI/TestPyPI.

Usage

Please see the Command-line Reference for details.

Please have a look at the docker-compose.yml file under scripts/iam to start the stack with Keycloak and Open Policy Agent locally. There is a README.md file that explains how to use it.

The file scripts/iam/keycloak/realm-export.json can be used to import an already configured realm into Keycloak.

The files under scripts/postman can be used to setup Postman with a configuration that is ready to perform the requests for the whole stack.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, fastgeoapi is free and open-source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

MCP Server (Model Context Protocol)

fastgeoapi includes an optional integrated MCP server that exposes OGC API endpoints as tools for AI assistants and LLM-based applications. The MCP server is built using FastMCP and automatically generates tools from the pygeoapi OpenAPI specification.

Features

• Automatic Tool Generation - Tools are generated from the OGC API OpenAPI spec
• OAuth Authentication - Supports OIDC authentication with any OAuth provider (Logto, Auth0, Keycloak, etc.)
• RFC 9728 Compliant - Implements OAuth 2.0 Protected Resource Metadata
• Dynamic Client Registration - Compatible with mcp-remote and other MCP clients
• Provider Agnostic - Works with any OIDC-compliant IdP via fastmcp's OIDCProxy (Logto, Auth0, Keycloak, etc.)
• Stateless Streamable HTTP - Every request is self-contained: machine suspends and redeploys are transparent to connected clients
• Server card (SEP-2127) - Every deployment with MCP enabled publishes /.well-known/mcp-server-card, so install choosers and clients configure themselves from one document

Enabling the MCP Server

To enable the MCP server, set the FASTGEOAPI_WITH_MCP environment variable:

# In your .env file
DEV_FASTGEOAPI_WITH_MCP=true

# Or for production
PROD_FASTGEOAPI_WITH_MCP=true

The MCP server will be mounted at /mcp endpoint.

Configuration

Basic Configuration (No Authentication)

# .env file
ENV_STATE=dev
DEV_FASTGEOAPI_WITH_MCP=true
# Explicit opt-in: without authentication configured, MCP refuses to
# start unless you acknowledge the unauthenticated (passthrough) mode.
DEV_FASTGEOAPI_MCP_ALLOW_UNAUTHENTICATED=true
DEV_PYGEOAPI_CONFIG=pygeoapi-config.yml
DEV_PYGEOAPI_OPENAPI=pygeoapi-openapi.yml

With OAuth Authentication

To enable OAuth authentication for the MCP server, configure JWKS:

# .env file
ENV_STATE=dev
DEV_FASTGEOAPI_WITH_MCP=true
DEV_JWKS_ENABLED=true
DEV_OIDC_WELL_KNOWN_ENDPOINT=https://your-idp.example.com/.well-known/openid-configuration
DEV_OIDC_CLIENT_ID=your-client-id
DEV_OIDC_CLIENT_SECRET=your-client-secret

# Optional MCP OAuth tuning (see docs/mcp/configuration.md for details)
# Consent screen behavior: always | remember | external | never
DEV_FASTGEOAPI_MCP_CONSENT_MODE=remember
# Client-facing access-token lifetime, decoupled from the IdP expires_in
DEV_FASTGEOAPI_MCP_ACCESS_TOKEN_EXPIRY_SECONDS=86400

The requested scopes include offline_access by default, so the IdP issues a refresh token and MCP clients can renew silently instead of re-running the browser authorization on every token expiry (make sure your IdP allows that scope for the client).

Security & Authentication Flows

The MCP server supports multiple security configurations depending on your deployment needs.

Supported OAuth 2.0 Flows

OAuth Proxy Architecture

When OAuth is enabled, the MCP server acts as an OAuth Proxy implementing:

• RFC 8414 - OAuth 2.0 Authorization Server Metadata
• RFC 9728 - OAuth 2.0 Protected Resource Metadata
• RFC 7636 - Proof Key for Code Exchange (PKCE)
• RFC 7591 - OAuth 2.0 Dynamic Client Registration

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   MCP Server    │────▶│   Identity      │
│  (mcp-remote)   │     │  (OAuth Proxy)  │     │   Provider      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │  1. Discovery         │                       │
        │──────────────────────▶│                       │
        │  /.well-known/...     │                       │
        │                       │                       │
        │  2. DCR (register)    │                       │
        │──────────────────────▶│                       │
        │                       │                       │
        │  3. Authorization     │  4. Redirect to IdP   │
        │──────────────────────▶│──────────────────────▶│
        │                       │                       │
        │                       │  5. Auth Code         │
        │                       │◀──────────────────────│
        │  6. Token Exchange    │                       │
        │◀──────────────────────│                       │
        │                       │                       │
        │  7. MCP Requests      │  8. In-process ASGI   │
        │  (with Bearer token)  │     call to pygeoapi  │
        │──────────────────────▶│──────────────────────▶│

Security Features

Supported Identity Providers

The MCP server is provider-agnostic and works with any OIDC-compliant IdP:

• Logto - Tested with OAuth proxy and DCR
• Auth0 - Full OIDC support
• Keycloak - Full OIDC and OPA integration
• Okta - Standard OIDC flows
• Azure AD - Microsoft identity platform
• Google - Google OAuth 2.0

Using the MCP Server

The shortest way in is the install badge at the top of this page: it reads the demo's server card and shows the install path for your client — deep link, command line, config snippet or connector walkthrough. The demo's login accepts GitHub accounts. Your own deployment publishes its own card; see the how-to.

With Claude Desktop (native connector, recommended)

Claude Desktop supports remote MCP servers natively as custom connectors — no local shim or config-file edit required:

1. Open Settings → Connectors → Add custom connector
2. Paste the server URL: https://your-domain.com/mcp/ (trailing slash optional)
3. Complete the OAuth login in the browser popup on first use

If an older mcp-remote-based entry for the same server is still in claude_desktop_config.json, remove it — the two clients race through the OAuth flow and can leave the tools list stuck.

With stdio-only clients (mcp-remote)

For MCP clients that only speak stdio, front the server with mcp-remote:

{
  "mcpServers": {
    "fastgeoapi": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-domain.com/mcp/"]
    }
  }
}

For local development over plain HTTP, add the --allow-http flag. Note that mcp-remote keeps tokens only in process memory, so every restart re-runs the full OAuth dance.

Direct Streamable HTTP Connection

The server speaks MCP over the Streamable HTTP transport (the legacy /mcp/sse endpoint no longer exists) and negotiates the protocol version per connection, so both the sessionless 2026-07-28 revision and the earlier handshake work. Clients with native remote MCP support connect directly to:

http://localhost:5000/mcp/

Available Tools

The MCP server exposes all OGC API endpoints as tools. Names come from the OpenAPI operationIds, so collection-specific tools embed the collection name (the demo configuration yields 27 tools). For example:

OAuth Discovery Endpoints

When OAuth is enabled, the following RFC-compliant endpoints are available:

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claude Desktop                        │
│                    or MCP Client                         │
└─────────────────────┬───────────────────────────────────┘
                      │ MCP Protocol (Streamable HTTP)
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   fastgeoapi                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │              MCP Server (/mcp)                     │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │  │
│  │  │ OAuth Proxy │  │ Tool Router │  │ HTTP      │  │  │
│  │  └─────────────┘  └─────────────┘  └───────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
│                          │                               │
│                          ▼                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │           pygeoapi OGC API (/geoapi)              │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Credits

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.