---
title: "Riferimento dell’Open API e del server MCP di Fincanva"
description: "L’Open API e il server MCP di Fincanva espongono le stesse operazioni: questo riferimento le elenca una per una con scopo, parametri, risultati ed esempio."
canonical_url: "https://fincanva.com/it/docs/api-e-mcp/riferimento-dell-open-api-e-del-server-mcp-di-fincanva"
last_updated: "2026-10-01"
md_url: "https://fincanva.com/it/docs/api-e-mcp/riferimento-dell-open-api-e-del-server-mcp-di-fincanva.md"
---

# Riferimento dell’Open API e del server MCP di Fincanva

L’Open API di Fincanva e il server MCP di Fincanva espongono le stesse operazioni: ciascuna è un endpoint REST e uno strumento MCP con lo stesso nome, gli stessi parametri, lo stesso risultato e gli stessi limiti di piano. Un client AI le chiama come strumenti; il tuo codice le chiama via HTTPS. Ogni cifra che restituiscono porta la propria unità, e la pagina delle convenzioni spiega che cosa significano ogni unità e ogni segno.

## Come si invoca un’operazione di Fincanva?

- Via REST, invia `POST` a `https://app.fincanva.com/api/v1/research/<operation_id>` con i parametri in un corpo JSON e un’intestazione `Authorization: Bearer` con una chiave API o un token di accesso OAuth.
- Via MCP, aggiungi `https://app.fincanva.com/mcp` a un client MCP; ogni operazione è uno strumento con il nome del suo id, e il client accede con il tuo account Fincanva.
- Il documento OpenAPI 3.1 di tutte le operazioni REST si trova in `https://app.fincanva.com/api/v1/research/openapi.json`.

## Che cosa restituisce ogni operazione di Fincanva?

Una chiamata REST riuscita restituisce `status: true` e un oggetto `data` che contiene `result` (il risultato proprio dell’operazione), `summary` (poche righe di testo), `assumed` (ogni valore che l’operazione ha riempito perché la richiesta lo ometteva, con il motivo), `dataVersion` (la build notturna dei dati da cui provengono le cifre, oppure null quando nulla è stato calcolato dai dati di mercato) e, quando il risultato è una serie, `chart`. Un risultato registrato porta anche `recipeId` (ciò che lo riproduce: la stessa operazione, lo stesso input e la stessa versione dei dati) e `permalink` (l’indirizzo permanente del risultato su Fincanva). Via MCP lo stesso oggetto è il contenuto strutturato dello strumento e il riepilogo ne è il testo.

Il significato di ogni unità e di ogni segno è scritto una volta sola, nelle [convenzioni](/it/docs/api-e-mcp/unita-e-convenzioni-dell-open-api-e-del-server-mcp-di-fincanva).

## Quali operazioni di Fincanva puoi invocare?

**Creazione delle strategie**

- [Elenca i metodi di allocazione](/it/docs/api-e-mcp/elenca-i-metodi-di-allocazione) — `list_allocation_methods`. Elenca i metodi di allocazione che Fincanva offre — il modo in cui una strategia, o una Combinata tra le sue strategie, stabilisce il peso di ogni posizione — con le impostazioni proprie di ciascun metodo, i valori predefiniti e i limiti, i livelli a cui funziona e se il tuo piano lo include.
- [Elenca i preset delle condizioni di rischio](/it/docs/api-e-mcp/elenca-i-preset-delle-condizioni-di-rischio) — `list_risk_rule_presets`. Elenca le condizioni di rischio pronte che una strategia può attivare — il VIX, il rapporto VIX, i TIPS, le regole sulla curva dei rendimenti, l’S&P 500 rispetto alla sua media a 200 giorni e il suo momentum a 12 mesi — ciascuna con la regola che applica: l’indicatore, le soglie di risk-off e di risk-on, le settimane di ritardo e i valori che puoi modificare.
- [Descrivi il modello di strategia](/it/docs/api-e-mcp/descrivi-il-modello-di-strategia) — `describe_portfolio_model`. Descrive il modello di strategia di Fincanva una sezione alla volta — il livello della Combinata (il `portfolio` dell’API), le condizioni di rischio, l’allocazione, le strategie dentro una Combinata (i `models` dell’API), le uscite dalle posizioni, la selezione e le impostazioni di simulazione — elencando ogni campo con il tipo, l’unità, il valore predefinito, i limiti e i valori ammessi, e il limite del tuo piano dove ce n’è uno.

**Screening**

- [Elenca i filtri dello screener](/it/docs/api-e-mcp/elenca-i-filtri-dello-screener) — `list_screen_filters`. Cerca nel catalogo dei filtri dello screener per parole nel nome o nella descrizione di un filtro, per concetto d’investimento (value, momentum, quality e altri), per livello (asset, sector, market), per categoria o per tipo di asset, e restituisce ogni filtro trovato con gli input che accetta e i tipi di confronto che supporta.
- [Descrivi un filtro dello screener](/it/docs/api-e-mcp/descrivi-un-filtro-dello-screener) — `describe_screen_filter`. Restituisce un filtro dello screener per intero: che cosa misura, gli input che accetta (come quanti mesi o bilanci prima viene letto il suo valore), ogni relazione che supporta (maggiore di, tra, i primi N, rispetto all’aggregato di mercato o di settore, rispetto al proprio passato), i termini di confronto di ciascuna relazione con i valori ammessi e quelli predefiniti, e l’unità di ogni valore.

## Quali codici di errore può restituire un’operazione di Fincanva?

- `invalid_input` — HTTP 422. I parametri non corrispondono allo schema dell’operazione; `details` elenca ogni problema con il suo campo.
- `payload_too_large` — HTTP 413. Il corpo della richiesta è più grande di quanto un’operazione accetti; `details.maxBytes` indica il limite. Non è stato eseguito né addebitato nulla.
- `result_too_large` — HTTP 422. La richiesta era valida, ma il suo risultato è più grande di quanto Fincanva conservi (`details.maxBytes`; `details.what` indica il valore). L’esecuzione viene rimborsata. Restringila (meno strumenti, un periodo più breve, meno passi) ed eseguila di nuovo.
- `ambiguous` — HTTP 422. Un nome che hai indicato corrisponde a più strumenti; `details` elenca i candidati, quindi scegline uno e chiama di nuovo.
- `not_resolved` — HTTP 422. Un nome che hai indicato non corrisponde a nessuno strumento che Fincanva ha.
- `insufficient_history` — HTTP 422. Gli strumenti non hanno abbastanza storico per il periodo o il lookback richiesto.
- `unauthorized` — HTTP 401. La chiave API o il token di accesso manca, è scaduto o è stato revocato.
- `plan_limit` — HTTP 403. Il tuo piano non include questa operazione o questa impostazione; `unlockedBy` indica il piano più basso che la include.
- `toolset_disabled` — HTTP 403. La famiglia dell’operazione è disattivata per questa connessione MCP; attivala nelle impostazioni della connessione in Fincanva.
- `licence` — HTTP 403. I dati di cui questa operazione ha bisogno non possono essere serviti tramite l’API o MCP secondo i termini del loro fornitore.
- `quota_exhausted` — HTTP 429. La quota mensile di chiamate, di esecuzioni pesanti o di report di ricerca è esaurita; `resetsAt` indica la data in cui si azzera.
- `not_found` — HTTP 404. L’operazione, oppure un elemento che hai indicato come un filtro, non esiste.
- `busy` — HTTP 503. Fincanva è al limite della capacità per questo tipo di esecuzione; non è stato addebitato nulla sulla tua quota, quindi riprova a breve.
- `engine_failed` — HTTP 502. Il calcolo è fallito da parte di Fincanva; non è stato addebitato nulla sulla tua quota.
- `internal` — HTTP 500. Un errore imprevisto da parte di Fincanva; non è stato addebitato nulla sulla tua quota.

Fincanva ha uno scopo solo educativo e illustrativo: non è una consulenza finanziaria personalizzata, e i risultati passati o simulati non indicano quelli futuri. [Leggi l'Addendum ai Termini](https://fincanva.com/it/terms/addendum#section-3)