# Quickstart

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

Due percorsi: chiamare l'API REST dal codice, oppure aggiungere il server MCP a un agente AI. Entrambi usano lo stesso account e le stesse 100 chiamate gratuite al mese.

## Chiamare l'API dal codice

### Creare una chiave API

1. Accedi su [terra-lab.ai/login](https://terra-lab.ai/it/login). Un account è gratuito e non richiede carta.
2. Apri [Dashboard, MCP](https://terra-lab.ai/it/dashboard/mcp), poi **Advanced**, **API keys**.
3. Dai un nome alla chiave, accetta i termini dell'API e clicca **Create key**.
4. Copia subito la chiave: inizia con `tlk_` e viene mostrata una sola volta.

Conservala in una variabile d'ambiente, mai nel codice:

```bash
export TERRALAB_API_KEY="tlk_your_key_here"
```

### Verificare la chiave

`GET /v1/me` restituisce il tuo account e le chiamate che ti restano questo mese.

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

Un `401` significa che la chiave manca, contiene un errore o è stata revocata.

### Fare la prima chiamata a un tool

Trova le coordinate di un indirizzo con `find_places`:

```bash
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"}'
```

```python
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"])
```

```javascript
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);
```

La risposta è un oggetto JSON: `structuredContent` contiene il risultato con le sue `sources`, `content` lo stesso risultato come testo, e `isError` indica se il tool ha rifiutato la richiesta.

### Andare oltre

- Estrai edifici e strade di un'area con [extract_open_data](https://terra-lab.ai/docs/api/extract_open_data).
- Ottieni quota, un profilo o le curve di livello con [get_elevation](https://terra-lab.ai/docs/api/get_elevation).
- Consulta tutti i 29 tool nel [riferimento API](https://terra-lab.ai/docs/api).

## Aggiungere TerraLab a un agente AI

In Claude Code, un solo comando:

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

Poi esegui `/mcp` in Claude Code e accedi a TerraLab. Per Claude, ChatGPT, Cursor, Codex e VS Code, vedi [Server MCP](https://terra-lab.ai/it/docs/mcp).

Prova a chiedere, per esempio: "Mostra gli edifici entro 500 m dalla stazione di Lyon Part-Dieu e dammi un GeoPackage."

Source: https://terra-lab.ai/it/docs/quickstart · Updated 2026-10-27