geobs-mcp

Open-source MCP server for accessing Basel-Stadt geospatial data via STAC, OGC API Features and GeoBS APIs.

geobs-mcp is a stateless, read-only Remote MCP server for Cloudflare Workers. It exposes five focused geo tools instead of a generic HTTP proxy. The first PoC supports the public GeoBS STAC catalog, OGC API Features/WFS3, Search API v2 and Grundstückinfo.

Status

V1 PoC is locally functional and deployable. It uses:

• TypeScript and Cloudflare Workers

• the stable MCP TypeScript SDK v2 via @modelcontextprotocol/server

• Cloudflare's stateless createMcpHandler

• Streamable HTTP at /mcp

• no Durable Objects, database, storage, queue, OAuth or LLM

The design follows the current Cloudflare stateless MCP handler documentation, the MCP transport specification, and the official OpenAI guidance for building and connecting MCP-backed plugins.

Related MCP server: mcp-arcgis-seattle

Tools

All tools advertise read-only, non-destructive, idempotent and closed-world annotations. Their inputs and structured outputs have JSON schemas.

Quick start

Requirements: Node.js 20 or newer and a valid GeoBS Search API key.

npm install

Copy the example local secret file:

Copy-Item .dev.vars.example .dev.vars

Set only your own key in .dev.vars:

GEOBS_API_KEY="your-key"

.dev.vars and .env files are ignored by Git. Never put a real key in source, tests, fixtures, the Wrangler configuration or logs.

Start the Worker:

npm run dev

The local URLs are normally:

• health: http://127.0.0.1:8787/

• MCP: http://127.0.0.1:8787/mcp

Opening /mcp in a browser is not an MCP test; the endpoint expects protocol requests.

Test with MCP Inspector

Start the current Inspector web UI:

npx @modelcontextprotocol/inspector@latest

Choose Streamable HTTP and connect to http://127.0.0.1:8787/mcp.

The CLI can verify schemas and invoke a tool without a browser:

npx @modelcontextprotocol/inspector@latest --cli http://127.0.0.1:8787/mcp --method tools/list --strict --format json

npx @modelcontextprotocol/inspector@latest --cli http://127.0.0.1:8787/mcp --method tools/call --tool-name search_datasets --tool-arg query=Strassennamen limit=2 --format json

Tests

npm run check
npm run test:integration

npm run check runs strict TypeScript checking and unit tests. Live integration tests are separate and clearly marked. Tests that use Search v2 or Grundstückinfo are skipped when GEOBS_API_KEY is absent; the anonymous STAC and WFS3 tests still run.

The validated V1 scenarios are:

• discover datasets for Strassen

• load STAC metadata and assets for STNA (Strassennamen)

• query WFS3 near Dufourstrasse 40 in EPSG:2056

• with a key: resolve the address, dynamically find its parcel/E-GRID and retrieve Grundstückinfo

• list and call the five tools through the Streamable HTTP MCP endpoint

Deploy to Cloudflare Workers

Authenticate Wrangler without changing unrelated account resources:

npx wrangler login

Store the GeoBS key as the required Worker secret. Wrangler prompts for the value and does not print it:

npx wrangler secret put GEOBS_API_KEY

Run checks and deploy:

npm run check
npm run deploy

Wrangler prints a URL similar to:

https://geobs-mcp.<your-subdomain>.workers.dev

The Remote MCP URL is that URL plus /mcp.

Smoke-test the deployed server:

npx @modelcontextprotocol/inspector@latest --cli https://geobs-mcp.<your-subdomain>.workers.dev/mcp --method tools/list --strict --format json

View runtime logs and deployments:

npx wrangler tail geobs-mcp
npx wrangler deployments list
npx wrangler versions list

Deploy an update with npm run deploy. Roll back interactively to the previous version, or specify a known version ID:

npx wrangler rollback
npx wrangler rollback <VERSION_ID>

A rollback immediately creates a new active deployment. No storage migration is involved because this Worker has no persistent infrastructure.

Connect to ChatGPT

Current official OpenAI documentation explicitly allows read-only plugin MCP servers to operate anonymously. Authentication discovery is needed only for tools that require an account. V1 therefore intentionally has no OAuth/OIDC stack.

After deployment:

1. Confirm the public HTTPS /mcp URL with MCP Inspector.

2. In ChatGPT settings, open Security and login and enable Developer mode. Availability can depend on account and workspace policy.

3. Open ChatGPT Plugins, add a connection, and enter the complete https://…workers.dev/mcp URL.

4. Review the five discovered tools and start a new conversation with the connection enabled.

5. Try: Gib mir alle verfügbaren Informationen zur Dufourstrasse 40.

For a private or workspace-only test, developer mode is the intended route; public plugin submission is not required. If a future deployment exposes user-specific data or write actions, implement MCP-conformant OAuth 2.1 then—not in this read-only V1.

Security model

• Requests can reach only the fixed https://api.geo.bs.ch origin.

• No tool accepts a URL, HTTP method, SQL statement or raw query string.

• IDs, property names, filter values, CRS values, result counts and spatial radii are validated.

• Feature responses are limited to 25 records and MCP output to approximately 250 KB.

• GeoBS requests have abort timeouts and response byte limits.

• Redirects are not followed.

• The Search/Grundstückinfo key is sent only in the server-side apikey header.

• Errors contain stable codes and no stack traces, response bodies or secrets.

Expected error codes include INVALID_INPUT, NO_RESULTS, DATASET_NOT_FOUND, COLLECTION_NOT_FOUND, UPSTREAM_UNAVAILABLE, TIMEOUT, RATE_LIMIT, INVALID_UPSTREAM_RESPONSE, RESPONSE_TOO_LARGE and MISSING_API_KEY.

Because the endpoint is anonymous, anyone who knows the deployed URL can invoke its bounded read-only tools and consume Worker/API capacity. Add edge rate limiting if the URL is shared broadly.

Architecture

src/
  clients/          GeoBS HTTP clients and response types
  tools/            validation, orchestration and response mapping
  mcp/server.ts     five MCP tool registrations
  http.ts           origin allowlist, timeout, size and error handling
  index.ts          stateless Cloudflare Worker entry point
test/
  unit/             mocked API and validation tests
  integration/      explicitly live GeoBS tests
docs/
  api-analysis.md   observed APIs and STAC↔WFS3 findings
  workflow.md       Dufourstrasse workflow and likely V2 tools

GeoBS domain logic is independent of the Worker entry point and can be tested with injected fetch mocks.

Further documentation

• Observed GeoBS APIs and STAC↔WFS3 analysis

• End-to-end workflow and V2 outlook

• GeoBS terms of use

License

MIT