MCP Examples

How LLMs use the MCP server to help users create maps.

Example 1: Simple Country Map

User: "I need a map of Canada"

LLM process:

1. Call list-locations?type=country&q=canada
2. Get Canada's location ID
3. Call get-api-example?scenario=country-map
4. Customize with Canada's ID

LLM Response:

Here's the API request:

curl -X POST 'https://api.smavatar.com/api/v1/projects/{project_id}/jobs/maps' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "fde40c8b-4d20-4839-960d-a7685ef3afc0",
    "width": 1400,
    "height": 900,
    "theme": "modern",
    "output_format": "png"
  }'

The job completes quickly.

Example 2: Quiz Map with Highlighting

User: "Create a US map quiz where students identify Idaho"

LLM process:

1. Call list-locations?type=country&q=united states
2. Call list-locations?type=subdivision&q=idaho
3. Generate quiz (no labels) and answer key (with labels)

LLM Response:

I'll create two maps—a quiz and answer key.

Quiz (no labels):

{
  "location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
  "theme": "modern",
  "configuration": {
    "show_subdivision_labels": false,
    "highlight_subdivisions": [{
      "subdivision_code": "us-id",
      "fill_color": "#3498db",
      "opacity": 0.7,
      "show_label": false
    }]
  }
}

Answer key: Same request with "show_subdivision_labels": true and "show_label": true.

Example 3: Map with Rivers

User: "Show me California with its major rivers"

LLM process:

1. Call list-locations?type=subdivision&q=california
2. Call list-features?location_id={ca_id}&type=river (requires API key)
3. Build request with features

LLM Response:

Here's how to generate California with rivers:

{
  "location_id": "{california-id}",
  "theme": "modern",
  "configuration": {
    "show_features": true,
    "show_river_labels": true
  }
}

Major rivers like the Sacramento and San Joaquin are included automatically.

Example 4: Checking Capabilities

User: "Can you create a 3D map of Paris streets?"

LLM process:

1. Call get-capabilities
2. Find 3D and street-level maps are not supported

LLM Response:

SMAvatar doesn't support 3D maps or street-level detail. It's designed for educational geography maps.

What SMAvatar can do:

• Country and state maps
• Region highlighting
• Rivers and lakes
• Multiple themes

For 3D street maps, try Google Maps or Mapbox.

Would you like a country-level map of France instead?

Example 5: Multiple Highlights

User: "Create a map showing the Pacific states"

LLM process:

1. Call list-locations?type=country&q=us
2. Call list-locations?type=subdivision&q=washington
3. Call list-locations?type=subdivision&q=oregon
4. Call list-locations?type=subdivision&q=california
5. Build request with all three

LLM Response:

Here's a map highlighting Washington, Oregon, and California:

{
  "location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
  "theme": "modern",
  "configuration": {
    "highlight_subdivisions": [
      { "subdivision_code": "us-wa", "fill_color": "#3498db", "opacity": 0.7 },
      { "subdivision_code": "us-or", "fill_color": "#3498db", "opacity": 0.7 },
      { "subdivision_code": "us-ca", "fill_color": "#3498db", "opacity": 0.7 }
    ]
  }
}

Integrating with Your LLM

To add SMAvatar MCP to your AI application:

1. Register tools — Add MCP tool definitions to your function calling
2. Set base URL — https://api.smavatar.com/api/mcp/tools/
3. Parse responses — Format JSON responses for users
4. Include API key — Required for list-features and get-feature-details

See the Tools Reference for complete tool documentation.