Linking MCP geocontext and MCP carto : in search of the best solution

[esgn]

I was focused on geocontext and gpf-schema-store and did not look into mcp-carto enough till now. I should have.

Current status in production

The current happy path is

GeoContext v0.9.8
  ↓
returns:
  method: POST
  url: https://data.geopf.fr/wfs
  query: {...}
  body: cql_filter=...
  get_url: https://data.geopf.fr/wfs?...&cql_filter=...
  ↓
LLM
  takes get_url
  ↓
MCP Carto v0.1.2
  receives get_url in layers[].data_url
  ↓
Carto UI
  detects cql_filter
  sends a POST request to data.geopf.fr/wfs
  displays the GeoJSON

The less happy path is

GeoContext v0.9.8
  ↓
returns:
  method: POST
  url: https://data.geopf.fr/wfs
  query: {...}
  body: cql_filter=...
  get_url: null
  ↓
LLM
  cannot use the normal get_url → layers[].data_url handoff
  ↓
LLM may try to recover by rebuilding a long data_url from:
  url + query + body.cql_filter
  ↓
MCP Carto v0.1.2
  receives the rebuilt URL in layers[].data_url
  ↓
Carto UI
  detects cql_filter in data_url
  extracts cql_filter
  removes cql_filter from the URL
  sends a POST request to data.geopf.fr/wfs
  ↓
If the rebuilt URL is valid:
  receives the GeoJSON
  displays it on the map
  ↓
If the LLM fails to rebuild the URL correctly:
  no GeoJSON is loaded
  nothing is displayed

Another bad mistake I've just spotted : https://github.com/ignfab/mcp-carto/blob/166bcff0189c7ff1f605b0c90c188e127fde7d0e/server.ts#L64 => should be result_type=request with gpf_wfs_get_features tool !

I wonder how it can work so well in demo 🤪

Possible solutions to stabilize the contract

1. Update MCP Carto to accept a structured http_request source with method, url, query, headers, and body, instead of only accepting layers[].data_url => could be ok but we will still have this problem gpf_wfs_get_features - ensure that it doesn't returns huge geometries (4Mo) in cql_filter #151

2. Expose a stable /layers/{id}.geojson URL from GeoContext so MCP Carto can consume a simple GeoJSON layer without knowing the underlying WFS complexity => Geocontext acting as WFS proxy

3. Store the request “recipe” in GeoContext rather than the result, then replay that recipe when Carto calls the layer URL. => Geocontext serving the POST request recipe via URL to bypass the LLM

4. Temporarily materialize the GeoJSON in GeoContext, then provide Carto with a simple URL pointing to the precomputed result => Geocontext acting as WFS caching proxy

5. Use an MCP resource from GeoContext to carry the GeoJSON or compiled request, then evolve Carto so it can consume that resource instead of a raw URL. => MCP resource are not supported by a lot of AI assistant

6. Pass query with references directly to MCP Carto and let Carto do the work of building the query once again. => a bit cumbersome

Discussion

Let's say we choose the /layers/{id}.geojson which proxifies the WFS interrogation => it smells like valkey + http routes of mcp-framework

[Viglino]

• MCP Carto can simplify the filtering geometry before sending the request
• MCP Carto can get the bbox and filter the features client side
• MCP Carto can tile the request to limit the number of return objects or use WFS pagination (when enable)
• MCP Carto can optimaze the rendering

[esgn]

After our short talk, here is a first try. Do we all agree or not ? If not please describe your alternative solution in details :)

Target contract

MCP Carto should not become a WFS client.

It should not have to:

- rebuild WFS requests;
- extract `cql_filter` from URLs;
- switch from GET to POST;
- handle WFS pagination;
- understand GeoContext internals.

The target contract should be:

MCP Carto receives a short GeoJSON URL.
MCP Carto fetches it.
MCP Carto displays it.

For example:

{
  "layers": [
    {
      "title": "Buildings",
      "color": "#ff0000",
      "data_url": "https://geollm.beta.ign.fr/geocontext/layers/abc123.geojson"
    }
  ]
}

Proposed target architecture

GeoContext should expose short-lived layer URLs:

/layers/{id}.geojson

The flow would be:

1. The LLM asks GeoContext for features using gpf_wfs_get_features with a specific output mode, for example result_type: "layer" or output_mode: "layer_url".
2. GeoContext builds and validates the corresponding WFS request from the tool arguments, including the target type_name, filters, spatial filter / geometry_ref, output format, ...
3. GeoContext stores a temporary WFS request recipe, for example in Valkey, with a TTL. The stored recipe contains the WFS endpoint, method, query parameters, POST body if needed, pagination settings, and limits.
4. GeoContext returns a short layer_url, for example /layers/{id}.geojson, together with minimal metadata such as expiration time, source type, and target type_name.
5. The LLM passes that layer_url to MCP Carto as layers[].data_url, without rebuilding the WFS URL or copying the cql_filter.
6. MCP Carto fetches the URL as a regular GeoJSON layer and does not need to know whether the original WFS request was GET, POST, paginated, or based on a CQL filter.
7. When the layer_url is requested, GeoContext replays the stored WFS request, handles WFS-specific details such as POST, CQL, pagination, timeouts and limits, then returns a GeoJSON FeatureCollection.

In practice:

GeoContext `gpf_wfs_get_features` tool
  → stores WFS request recipe
  → returns /layers/{id}.geojson

MCP Carto
  → fetches /layers/{id}.geojson

GeoContext layer resolver
  → reads recipe
  → calls WFS
  → handles POST / CQL / pagination / limits
  → returns GeoJSON

What should be stored

The stored object should be a request recipe, not the resulting GeoJSON.

For example (not be implemented as is):

{
  "service": "https://data.geopf.fr/wfs",
  "method": "POST",
  "query": {
    "service": "WFS",
    "version": "2.0.0",
    "request": "GetFeature",
    "typeNames": "BDTOPO_V3:batiment",
    "outputFormat": "application/json"
  },
  "body": {
    "cql_filter": "INTERSECTS(...)"
  },
  "limits": {
    "page_size": 1000,
    "max_features": 5000,
    "max_response_bytes": 20000000
  }
}

This keeps the generated URL short while avoiding the need to materialize and store potentially large GeoJSON responses upfront.

Optional GeoJSON caching could be added later if needed, but it should not be required for the first implementation.

Responsibilities

GeoContext should own:

- WFS request construction;
- WFS request validation;
- POST vs GET handling;
- CQL filters;
- pagination;
- maximum feature count;
- maximum response size;
- timeout handling;
- clear errors when the result is too large.

MCP Carto should own:

- loading a GeoJSON URL;
- displaying the layer;
- styling;
- interaction;
- rendering optimizations.

The LLM should only pass a short URL between the two MCP servers.

Limits and safeguards

The /layers/{id}.geojson endpoint should not become a generic public WFS proxy.

It should be a short-lived layer resolver for requests created by GeoContext itself.

It should have strict safeguards:

- short TTL;
- generated IDs only;
- no arbitrary user-provided target URL;
- allowed WFS hosts only;
- maximum number of features;
- maximum number of WFS pages;
- maximum response size;
- request timeout;
- clear error if the result is too large.

If the result is too large to be returned as one GeoJSON layer, GeoContext should fail explicitly rather than trying to send an oversized response.

About mcp-framework

With the current mcp-framework setup, adding custom HTTP routes inside the same MCP HTTP server does not seem straightforward.

So the implementation could be split in two phases:

Phase 1:
- keep mcp-framework for the MCP server;
- add a small layer resolver HTTP endpoint beside it;
- use the same repository and shared code (wfs codebase for example);
- use the same temporary store, for example Valkey;
- route /layers/{id}.geojson to the resolver.

Phase 2:
- migrate to the official MCP SDK or another setup where GeoContext controls the HTTP server;
- expose both the MCP endpoint and the layer resolver endpoint from the same application if needed.

The important point is that the public contract remains stable:

GeoContext returns a short-lived GeoJSON layer URL.
MCP Carto consumes that URL.

Temporary fix

Do we really need a quick to apply temporary fix for this ?

The fix could be :

• Remove result_type=http_post_request and only returns small sized URLs and fail otherwise
• Add a simplification operation on geometry to try and make a request with cql_filter with geometry smaller. I'm not 100% sure that it will not take some time to perfect.

[LionelZoubritzky-IGN]

Thanks a lot for this summary, I completely agree with the proposed contract between geocontext and carto. However, I think it would be best to run the WFS request upfront and store the resulting GeoJSON, rather than storing the request itself.
Why?

• The request is meant to be executed anyway by carto, so I don't see the interest in delaying it.
• No need for GeoJSON caching: Valkey will already be storing the GeoJSON.
• geocontext can directly use the WFS response! The only case where there is no need to actually execute the request immediately is when the goal is only to display it with carto, but I don't see why this specific use-case should be considered the main one. There are plenty of contexts in which the user may want to display the result while also making use of it for further analysis, and in all of these use-cases, geocontext will need access to the response anyway.
• geocontext can pre-process the GeoJSON before storing it on Valkey, which makes handling large GeoJSON more manageable.
• The implementation seems much easier: when the geometry is requested, we send the WFS request, extract the geometry from the response, store it with Valkey, get an URL for it, and return the response where the geometry field is replaced with geometry_url with the link.

I think the only concern is that it can increase outgoing traffic from Valkey for large GeoJSON response, since their route will be WFS → Valkey → carto instead of WFS → carto. I'm not convinced this is catastrophic though... And if need be, we could always implement the proposed solution as a fallback when the GeoJSON gets too large (but I think that should be in a later step).

Please let me know if I misunderstood something!

EDIT: after discussion, there are two mistakes above:

• first, the stored GeoJSON contains the entire response, not only the geometry, so geocontext can make use of it
• a goal would be to have a stateless API that can be queried through an URL to get the GeoJSON. So the API should work independently of geocontext, which precludes the idea to feed it with an already queried GeoJSON.

[mborne]

@esgn

• With /layers/{id}.geojson, we have to "create" this layer by POSTing something to an API. we also have to store something at this API.
• Instead, I propose /api/v1/proxy-wfs?typename=BDTOPO_V3:batiment&intersects_feature_filter={"typename":"ADMINEXPRESS:departement","feature_id":"departement.25"} returning a GeoJSON collection with the parameters of the gpf_wfs_get_features tool (stateless possible / cacheable with a key based on query params) - could be done in APICARTO later (looks like the first try : https://apicarto.ign.fr/api/doc/wfs-geoportail#/)

Allows also :

• /api/v1/proxy-isochrone?lon={lon}&lat={lat}&distance={distance}

[mborne]

For now, we could create a dedicated issue to reemove result_type=http_post_request and only returns small sized URLs and fail otherwise ?

[esgn]

If I try and summarize we're now converging towards a proxy solution.

To recap we have multiple proxy options available :

1. A stateless WFS-backed Feature Query API. It exposes only the high-level query parameters supported by gpf_wfs_get_features, rather than raw WFS parameters. => Your proposal @mborne
2. A stateful GeoJSON layer resolver storing the WFS request recipe. GeoContext creates a short-lived layer URL, stores the validated WFS request recipe, then replays it when MCP Carto fetches the GeoJSON URL. => @esgn proposal
3. A stateful GeoJSON layer resolver storing the GeoJSON response. GeoContext executes the WFS request upfront, stores the resulting GeoJSON, then serves it through a short-lived layer URL. => No one's proposal

Remaining points which inhabit my brain:

• Number of HTTP request. Geocontext already makes one more request for spatial filtering with a feature reference (resolving the feature reference than passing it into a cql_filter).
  • With option 1, we have to resolve feature reference at proxy level before sending the cql_filter.
  • With option 2, we could cache the WFS request recipe with feature reference already resolved at proxy level and directly make only one HTTP request
  • With option 3, we are caching the final result. No HTTP request needed at proxy level.
• WFS Paging. We are not supporting this feature in geocontext for now. What will happen if we were to support it in our proxy ?
  • Option 1: paging can be handled inside the stateless proxy. The main risk is that MCP Carto waits for the proxy response while the proxy performs several upstream WFS requests. We would need strict limits on page count, feature count, response size and timeout.
  • Option 2: paging can also be handled by the layer resolver when MCP Carto fetches the short-lived GeoJSON URL. The same timeout and response-size concerns apply, because the final GeoJSON is still produced synchronously at display time
  • Option 3: paging would have to be handled upfront when GeoContext materializes the GeoJSON response. This makes the display path simpler for MCP Carto, but it moves the cost to the initial GeoContext call and may require storing large GeoJSON responses. We would still need limits on page count, feature count, response size, cache size and TTL.

Tentative conclusion

• Option 1 looks like the cleanest long-term architecture if we want a reusable, stateless, high-level Feature Query API.
• Option 2 is a pragmatic intermediate solution if we want to keep the public contract opaque and avoid designing a full stateless API immediately.
• Option 3 gives the simplest display path for MCP Carto, but it introduces heavier storage, cache invalidation and response-size concerns. It should probably remain an optimization or fallback rather than the default design.

[esgn]

@mborne , @LionelZoubritzky-IGN , @Viglino => ok for going forward with option 1 ?