> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finseo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrazione MCP

> Collega Finseo ad assistenti AI come Claude, ChatGPT e Cursor.

# Integrazione MCP

Finseo mette a disposizione un server Model Context Protocol (MCP) che permette agli assistenti AI di interrogare direttamente i tuoi dati di visibilità.

## Cos'è MCP?

MCP (Model Context Protocol) è uno standard per collegare i modelli AI a fonti di dati esterne. Con il server MCP di Finseo, puoi porre a Claude, ChatGPT o Cursor domande in linguaggio naturale sulla tua visibilità AI senza scrivere codice.

**Esempio**: apri Claude e chiedi:

> "Come è cambiata la visibilità del mio brand negli ultimi 30 giorni? Quali competitor sono davanti a me?"

Claude interroga automaticamente i tuoi dati Finseo e fornisce un'analisi.

## Guide al setup

* [Claude (claude.ai, Desktop, Code)](/it/mcp/claude-desktop) — OAuth, nessuna API key necessaria
* [ChatGPT (developer mode)](/it/mcp/chatgpt) — OAuth, nessuna API key necessaria
* [Cursor](/it/mcp/cursor) — API key tramite header

## Autenticazione

Il server MCP supporta due metodi di autenticazione:

| Metodo        | Ideale per                    | Come                                                                                                                |
| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **OAuth 2.1** | Claude, ChatGPT               | Aggiungi l'URL del server, accedi con il tuo account Finseo — il server supporta Dynamic Client Registration e PKCE |
| **API key**   | Cursor, client personalizzati | Invia `Authorization: Bearer sk_live_...` ([crea una key](https://app.finseo.ai/settings/api))                      |

## Tool disponibili

Tutti i tool sono **read-only**: recuperano dati e non li modificano mai.

| Tool                        | Descrizione                                                                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_projects`             | Elenca tutti i tuoi progetti                                                                                                                              |
| `get_visibility_metrics`    | KPI di visibilità inclusi il tasso "Visibility" della dashboard e il KPI "Citations" per il dominio proprio, con confronto rispetto al periodo precedente |
| `get_visibility_timeseries` | Visibilità, menzioni, posizione e sentiment per giorno (gli stessi valori del grafico della dashboard)                                                    |
| `list_prompts`              | Prompt monitorati con metriche, principali competitor e citazioni per prompt                                                                              |
| `get_competitor_ranking`    | Ranking di visibilità dei competitor sui modelli AI                                                                                                       |
| `get_top_sources`           | Fonti più citate con conteggi delle citazioni e tipi di fonte                                                                                             |
| `get_tags`                  | Elenca i tag con il numero di prompt                                                                                                                      |
| `get_query_fanouts`         | Query fan-out AI (sotto-query) ordinate per frequenza                                                                                                     |

I tool di analytics accettano i filtri opzionali `model` (es. `chatgpt`, `perplexity`, `ai_overview`, `gemini`, `grok`) e `tags` — gli stessi filtri della dashboard.

### Definizioni delle metriche

I tool restituiscono gli stessi numeri della dashboard di Finseo e li etichettano esplicitamente:

* **`visibilityRatePercent`** — quota di risposte AI analizzate che menzionano il tuo brand (il KPI "Visibility" della dashboard)
* **`promptCoveragePercent`** — quota di prompt monitorati con almeno una menzione (un numero diverso, di solito più alto)
* **`ownDomainCitations.total`** — risposte AI che citano il tuo dominio come fonte (il KPI "Citations" della dashboard)

## Endpoint

```
POST https://api.finseo.ai/v1/mcp
```

Il server implementa JSON-RPC 2.0 su Streamable HTTP e supporta `initialize`, `tools/list` e `tools/call`. Le richieste non autenticate ricevono un `401` con i metadati di discovery OAuth secondo la spec di autorizzazione MCP (RFC 9728).