@embed-earth/mcp-test

@embed-earth/mcp-test

MCP server for E2. It exposes search, cache, routing including feature-backed destinations, cloud/local compute, comparisons, user dataset storage, catalog discovery, and cell encode/decode over stdio. The e2_map_sources tool resolves the Planet basemap and published feature PMTiles sources for Map clients.

Product: embed.earth · Docs: MCP docs · Docs home

Related interfaces: SDK docs and CLI docs.

The MCP server is the agent-facing interface to the same capabilities exposed by the @embed-earth/sdk-test SDK and the @embed-earth/cli-test CLI.

Run

The e2_route tools use https://route.embed.earth by default. Set ROUTE_URL in the MCP host environment to use another compatible routing service.

npx -y @embed-earth/mcp-test

Add it to an MCP host using a standard stdio configuration:

{
  "mcpServers": {
    "e2": {
      "command": "npx",
      "args": ["-y", "@embed-earth/mcp-test"],
      "env": {
        "ROUTE_URL": "https://route.embed.earth"
      }
    }
  }
}

Do not place a real credential in a checked-in MCP configuration. ROUTE_URL is optional because the server already uses https://route.embed.earth.

Tool layout

Group	Tools	Purpose
Search	e2_search	Search features and return GeoJSON
Routing	e2_route, e2_route_to_feature	Run routing operations or route to an indexed feature
Compute	e2_compute, e2_compare	Run spatial primitives or compare features/areas
Catalogs	e2_features_search, e2_regions_search, e2_datasets_list	Discover available data
Local data	e2_cache, e2_storage_upload	Manage snapshots or index user data
Map	e2_map_sources	Resolve basemap and feature PMTiles
Cells	e2_encode, e2_decode, e2_neighbors	Encode, decode, and traverse cells

Input conventions

Input	Convention
feature	A feature key or numeric feature ID
area	A human-readable area name
area_id	An exact catalog ID; do not wrap it in a provider-specific prefix
mode	cloud, offline, or auto for search/compute
database	Optional local SQLite path for compute and upload workflows

e2_route accepts route, matrix, isochrone, mapMatch, locate, or height as its operation. e2_compute accepts NEAREST, DISTANCE, WITHIN, COUNT, DENSITY, COVERAGE, GAPS, or CLUSTER.

Use the regions catalog and features catalog to discover valid area, area_id, and feature inputs before calling a tool.

Practical tool calls

Search a named area, or use the raw exact area ID 4915 for New York:

{
  "feature": "restaurant",
  "area": "New York",
  "limit": 25,
  "mode": "auto"
}

{
  "feature": "restaurant",
  "area_id": "4915",
  "limit": 25
}

Run a spatial relation with e2_compute:

{
  "primitive": "NEAREST",
  "feature": ["restaurant"],
  "area_id": "4915",
  "near": "park",
  "distanceMeters": 500,
  "limit": 3,
  "mode": "cloud"
}

Route with e2_route by passing the operation and its body:

{
  "operation": "route",
  "body": {
    "locations": [
      { "lat": 40.74, "lon": -73.99 },
      { "lat": 40.71, "lon": -74.01 }
    ],
    "mode": "walking"
  }
}

Use e2_route_to_feature when the destination is a feature instead of a coordinate. e2_cache manages downloaded snapshots, e2_storage_upload imports GeoJSON/CSV/Parquet into SQLite, and e2_map_sources returns the Planet basemap plus published feature PMTiles sources.

Search, route, and compute in detail

e2_search: return matching features as GeoJSON

e2_search is data retrieval. It returns a GeoJSON FeatureCollection; it does not calculate a route or a spatial aggregate.

Input	Type	Meaning
feature	feature or feature array	Required catalog key(s) or numeric ID(s).
area	string or string array	Optional human-readable area name(s).
area_id	string or string array	Optional exact raw catalog ID(s).
mode	cloud, offline, auto	Optional execution backend; defaults to auto.
limit	integer	Optional row limit; defaults to 1000.
bbox	[minLng, minLat, maxLng, maxLat]	Optional bounding box.
where / properties	object	Optional typed source-column or property filters.

Use e2_search when an agent needs the matching feature records themselves.

e2_route: return a network journey

e2_route is network routing. Set operation and pass the matching request body; the default service is https://route.embed.earth.

operation	Required body fields	Result
route	locations	A route between ordered locations.
matrix	sources, targets	Travel metrics for source/target pairs.
isochrone	locations, optional contours	Reachable contours.
mapMatch	shape	A coordinate trace aligned to the network.
locate	compatible location body	Network information near locations.
height	compatible location body	Elevation information for locations.

e2_route_to_feature is the feature-destination variant: pass feature, from: [lat, lng], and optionally area or area_id; it resolves the nearest indexed destination before requesting the route.

e2_compute: return a spatial analysis result

e2_compute evaluates a spatial relationship or aggregate. It is not a raw record search and it does not return turn-by-turn directions.

Input	Type	Meaning
primitive	NEAREST, DISTANCE, WITHIN, COUNT, DENSITY, COVERAGE, GAPS, CLUSTER	Required analysis operation.
feature	feature array	Required catalog feature key(s) or ID(s).
area / area_id	string	Optional named or exact raw area.
near / within	feature	Optional relation feature.
distanceMeters	number	Relation distance; defaults to 500.
mode	cloud, offline, auto	Optional backend; defaults to auto.
database	string	Optional local SQLite path.
limit	integer	Optional output limit; defaults to 1000.

Use e2_compare to compare two features in one area (features) or one feature across two areas (areas or area_ids).

Choose e2_search for matching records, e2_route for network travel, and e2_compute for a spatial relationship or aggregate.

Open-source foundation

The server uses the standard MCP runtime and delegates geographic work to the SDK:

Tool	Role in the MCP package
Model Context Protocol SDK	Tool registration and stdio transport
Zod	Runtime validation for tool inputs
EmbedEarth SDK	Search, routing, compute, catalogs, storage, and map sources
H3	Spatial cell operations through the SDK
PMTiles	Published map source descriptors through the SDK

For terminal workflows, see the CLI package. For typed application code, see the SDK package.