Build a client application with an interactive map

As a best practice, use a separate access token to render maps in your application. This token may be different from the one used by your MCP server.

1. Create an API key with the following privilege(s) Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more :

   • Location services > Basemaps

2. Create an .env file in the root of your project and add the API key:

   MAP_API_KEY=your_api_key_here

3. Run the following prompt to build the application. Use the dropdown to select the language you want to use.

   Node.js Node.js Python

   Build a standalone Node.js + Express interactive map app using MCP for ArcGIS Location Services.
   
   Create:
   - server.js
   - package.json
   - mcp.example.json
   - README.md
   - public/index.html
   - public/app.js
   - public/styles.css
   
   Core features:
   - Geocode (find_address_candidates)
   - Reverse geocode (reverse_geocode)
   - Route solve (solve_route)
   - Elevation (elevation_at_locations)
   - ArcGIS interactive map visualization
   
   MCP requirements:
   - Read mcp.json from local folder, fallback to ../mcp.json
   - Use servers.alp-mcp-server.url + headers
   - JSON-RPC initialize + tools/call
   - Support JSON and SSE responses
   - Parse SSE data lines, use last valid JSON payload
   - Normalize errors/output
   
   Credential split:
   - Keep MCP bearer token for MCP server auth
   - Use separate map API key from app.mapApiKey or MAP_API_KEY / ARCGIS_API_KEY
   
   Endpoints:
   - GET /api/health
   - GET /api/tools
   - GET /api/arcgis-token
   - GET /arcgis-config.js
   - POST /api/geocode
   - POST /api/reverse
   - POST /api/route
   - POST /api/elevation
   
   Map/UI behavior:
   - Left control panel + right interactive map + result panel
   - Mode buttons: geocode, reverse, route, elevation
   - Click behaviors:
     - reverse mode fills x/y
     - route mode sets start/end
     - elevation mode appends points
   - Blue point markers for all operation points (#3284ff)
   - Blue route line (#4285F4) with blue start/end markers on top
   - Route zoom via view.goTo(routeGraphic)
   - Geocode popup includes route-ready x,y rounded to 5 decimals
   
   Run:
   - express dependency
   - scripts: start/dev = node server.js
   - default port 3000 with PORT override
   
   Acceptance:
   - All 4 workflows work end-to-end
   - Route line/markers render and zoom correctly
   - Geocode popup includes 5-decimal x,y
   - Map click workflows work in reverse/route/elevation modes

   The agent should:

   • Create a folder containing the application.
   • Provide instructions on how to run the application.
   • Implement a custom connector to MCP for ArcGIS Location Services using the provided URL and access token.
   • Use the connector to call MCP tools for geocoding, reverse geocoding, routing, and elevation based on user input.
   • Build an interactive map interface that updates dynamically with results from MCP tool calls.