Quickstart

Two paths: call the REST API from code, or add the MCP server to an AI agent. Both use the same account and the same 100 free calls a month.

Call the API from code

Create an API key

1. Sign in at terra-lab.ai/login. An account is free and needs no card.
2. Open Dashboard, MCP, then Advanced, API keys.
3. Name the key, accept the API terms and click Create key.
4. Copy the key now: it starts with tlk_ and is shown only once.

Keep it in an environment variable, never in your code:

export TERRALAB_API_KEY="tlk_your_key_here"

Check the key

GET /v1/me returns your account and the calls you have left this month.

curl https://mcp.terra-lab.ai/v1/me \
  -H "Authorization: Bearer $TERRALAB_API_KEY"

A 401 means the key is missing, mistyped or revoked.

Make your first tool call

Find the coordinates of an address with find_places:

curl -X POST https://mcp.terra-lab.ai/v1/tools/find_places \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"12 rue de la Paix, Annecy"}'

import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/find_places",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={"query": "12 rue de la Paix, Annecy"},
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])

const response = await fetch('https://mcp.terra-lab.ai/v1/tools/find_places', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: '12 rue de la Paix, Annecy' }),
});
const data = await response.json();
console.log(data.structuredContent);

The answer is a JSON object: structuredContent holds the result with its sources, content the same result as text, and isError says whether the tool refused the request.

Go further

• Extract buildings and roads for an area with extract_open_data.
• Get elevation, a profile or contour lines with get_elevation.
• Browse all 29 tools in the API reference.

Add TerraLab to an AI agent

In Claude Code, one command:

claude mcp add --transport http terralab https://mcp.terra-lab.ai/mcp

Then run /mcp in Claude Code and sign in to TerraLab. For Claude, ChatGPT, Cursor, Codex and VS Code, see MCP server.

Ask, for example: "Show the buildings within 500 m of Lyon Part-Dieu station and give me a GeoPackage."