DEV Community: Yoel Castaño

Querying Germany’s historical street catalogue with MCP

Yoel Castaño — Fri, 16 Oct 2026 19:22:40 +0000

A national street search can return two records with the same name and coordinates. If an assistant turns those into two independent streets, its answer is already misleading before it uses any nearby-service counts.

Callejear Germany now exposes a public, read-only MCP endpoint for exploring its historical catalogue. This walkthrough uses live responses checked on 16 October 2026 and shows how to keep the record identity and uncertainty intact. Disclosure: this is a maintainer publication, prepared with autonomous AI assistance.

Connect and discover the scope

Add a remote MCP server in a client that supports Streamable HTTP:

Endpoint: https://callejear.de/api/mcp
Authentication: none
Service name returned by initialization: callejear-germany

The client handles MCP initialization and tool discovery. The JSON examples below are parameters for the MCP tools/call method, not standalone REST request bodies.

Start with coverage:

{"name":"callejear_get_coverage","arguments":{}}

The checked response reports 593,062 historical street records, 10,650 municipality records and all 16 federal states. These are counts in the extract, not a claim that it is a complete or current official register. The export timestamp is not the date of the underlying observations.

The five tools are coverage discovery, municipality search, street search, street context and comparison. The connection documentation describes their sources and limits.

Resolve the municipality before the street

{"name":"callejear_search_municipalities","arguments":{"query":"Berlin","limit":3}}

This returned Berlin, Berlingen and Berlingerode. The exact Berlin match had state code DE-BE and municipality ID 110000000000. A text search can include other names containing the search term, so select the municipality explicitly rather than passing the first result through blindly.

Then search inside that municipality:

{"name":"callejear_search_streets","arguments":{"city_id":"110000000000","query":"Unter den Linden","limit":2}}

Here is the interesting part of the response, shortened to identity fields:

[
  {
    "id": "de:legacy:65eee30dd2de",
    "name": "U Unter den Linden",
    "catalog_url": null,
    "point": [52.517009, 13.388838],
    "identity_status": "legacy_not_independently_verified"
  },
  {
    "id": "de:legacy:b92a3b00da92",
    "name": "U Unter den Linden",
    "catalog_url": null,
    "point": [52.517009, 13.388838],
    "identity_status": "legacy_not_independently_verified"
  }
]

Both records have the same displayed name and stored point. A distinct database ID does not prove a distinct real-world street. The service preserves the historical records and reports that their identities have not been independently verified. It also omits an ambiguous catalogue link instead of inventing a slug.

A client should retain that distinction in its display. For this example, “two historical records matched” is supported; “two different streets matched” is not.

Read context without converting observations into claims about today

Use an ID returned by the search:

{"name":"callejear_get_street_context","arguments":{"street_id":"de:legacy:65eee30dd2de"}}

The checked response contained 6 supermarket, 4 pharmacy, 18 bakery and 59 cafe observations. Every metric was marked partial, used the unit observed_osm_records, and had an unknown source update date.

Those numbers refer to a 500-metre straight-line radius around a stored historical catalogue centroid. They are not a count of currently open, independently verified businesses along the whole street. Possible duplicate observations and unknown freshness limit what a client can infer.

The schema makes that visible:

{
  "key": "services.supermarkets",
  "value": 6,
  "unit": "observed_osm_records",
  "status": "partial",
  "radius_m": 500,
  "distance_method": "historical_haversine",
  "reference_geometry": "historical_catalog_centroid",
  "source_updated_at": null,
  "computed_at": null
}

Missing or unverified categories remain null. Do not turn null into zero in a chart or a sentence. Likewise, a fresh API response timestamp does not make its underlying data fresh.

A useful assistant prompt is: “Find the Berlin municipality, search the historical catalogue for Unter den Linden, and explain the identity and source-date limitations before showing any service observations.”

Compare records without ranking places to live

callejear_compare_streets accepts two to five returned street IDs and puts their context side by side. It does not provide a quality ranking. Comparing the two records above as if they were independent neighbourhood measurements would create a false distinction.

The service does not expose property prices, safety scores, demographic or political profiles, or housing recommendations. For client developers, the useful pattern is to preserve the response’s sources, limitations and unavailable dimensions through to the final answer.

Keep requests targeted. The public service allows 30 tool calls per minute and 100 per day per origin, with a shared daily budget of 1,000. Searches return at most 20 results per page. It is a small query interface, not a bulk export API.

Sources and reuse

Source attribution includes © OpenStreetMap contributors and © GeoBasis-DE / BKG. The documentation links the derived data extract and explains the ODbL terms and source attribution. Neither organisation endorses this independent service.

The public connection repository contains metadata and documentation, not the hosted implementation’s source. It is also registered as io.github.Habanacasta88/callejear-de in the official MCP Registry.

The main integration lesson is to treat a returned ID as a catalogue-record identifier and keep uncertainty attached to it. That makes the tool useful for exploration without asking the model to manufacture certainty the data does not contain.

Building a read-only city-data MCP: street identity, missing data and honest comparisons

Yoel Castaño — Fri, 16 Oct 2026 17:14:35 +0000

I work on Callejear, an independent project for exploring municipal data in Spain. We recently exposed a read-only MCP service for Madrid. The useful engineering lesson was that making data callable is only part of the job: the response contract must also prevent an assistant from drawing conclusions the data cannot support.

Here is a small integration example, followed by the decisions behind the interface. This article was prepared with AI assistance and checked against the project's implementation and documentation.

1. Discover coverage before answering questions

The service covers the municipality of Madrid, INE code 28079, rather than the whole Madrid region. Its current catalogue contains 9,400 official street codes from the municipal source dated 2026-10-13. Of these, 9,151 have a validated reference point; 249 remain searchable with missing location and metrics.

That distinction matters: complete coverage of a street catalogue does not imply complete coverage of the services near every street.

The first tool call should therefore be:

{
  "name": "callejear_get_coverage",
  "arguments": { "city_id": "28079" }
}

2. Search names, then use returned identifiers

A street name is a search term, not a reliable database key. Names have variants, and source records can disagree. The catalogue preserves four official-code/name conflicts explicitly instead of silently choosing a name.

{
  "name": "callejear_search_streets",
  "arguments": {
    "city_id": "28079",
    "query": "Alcalá",
    "limit": 5
  }
}

Use the identifier returned by the search when calling callejear_get_street_context. Do not construct an ID from a guessed slug. Search is paginated, with at most 20 results per page; cursors belong to a specific search and expire after 15 minutes.

3. A minimal JavaScript client

The project's documented client example uses Node 22.22.x and the pinned MCP client package below:

npm install --save-exact @modelcontextprotocol/client@2.3.1

Save this as consulta.mjs and run node consulta.mjs:

import {
  Client,
  StreamableHTTPClientTransport,
} from '@modelcontextprotocol/client';

const client = new Client({ name: 'madrid-data-example', version: '1.0.0' });

try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL('https://callejear.com/api/mcp')
  ));

  for (const request of [
    { name: 'callejear_get_coverage', arguments: { city_id: '28079' } },
    {
      name: 'callejear_search_streets',
      arguments: { city_id: '28079', query: 'Alcalá', limit: 5 },
    },
  ]) {
    const result = await client.callTool(request);
    if (result.isError) {
      console.error('Tool returned an error:', result.content);
      break;
    }
    console.log(JSON.stringify(result.structuredContent ?? result.content, null, 2));
  }
} finally {
  await client.close();
}

This is an anonymous Streamable HTTP endpoint. The service performs reads only and does not require credentials for other services.

4. Preserve the difference between null and zero

The four available dimensions count observed records for pharmacies, schools, supermarkets and libraries within 500 metres of a representative point, using Haversine distance.

They are partial historical observations. They do not measure an entire street, guarantee that a business is still open, or represent a complete inventory of unique establishments.

Consequently:

null means unavailable, not zero.
Zero means no matching records in the extract and search area, not proof that no service exists.
A higher count is not a score for safety, school quality or suitability for living.

callejear_compare_streets accepts two to five distinct street IDs. A client should preserve the definitions, radius, sources and limitations when presenting a comparison, rather than turning a count into an unsupported recommendation.

5. Treat payload size and tool errors as part of the contract

Responses are capped at 32 KiB. For larger comparisons, the full result is in structuredContent, while the text content may be a readable summary. A client that always parses content[0].text as JSON will break this contract.

Likewise, HTTP success does not guarantee tool success: an exhausted tool quota returns an MCP error result over HTTP 200. Check isError. HTTP throttling separately uses 429.

The public pilot has modest limits: 30 tool calls per minute and 100 per UTC day per origin, with a shared daily budget of 1,000. Cached responses also count. Use targeted queries rather than attempting a bulk crawl through the tools.

Sources and implementation notes

The Callejear MCP documentation includes the connection details, method, data downloads and limitations. The official registry identifier is com.callejear/madrid.

The street catalogue comes from the Ayuntamiento de Madrid's official street dataset, with municipal attribution and CC BY 4.0 terms. The OSM-derived extract retains OpenStreetMap attribution and ODbL terms. These are data licences, not a claim about a software licence. Neither source endorses this independent service.

For similar city-data tools, I would make coverage, missingness and provenance explicit in the first version of the response schema. Those details determine which answers a client can responsibly produce.