FinancialMD per agenti AI

Passaggio 1. Collega il server MCP

Il server MCP è disponibile su https://mcp.financial.md/mcp (Streamable HTTP, senza stato). Dispone di 50 strumenti di sola lettura. L'accesso è facoltativo: senza token risponde entro i limiti giornalieri previsti per l'accesso senza chiave.

Claude Code:

claude mcp add --transport http financial-md https://mcp.financial.md/mcp

Client che leggono una configurazione JSON (Cursor, VS Code, Windsurf e altri):

{
  "mcpServers": {
    "financial-md": { "type": "http", "url": "https://mcp.financial.md/mcp" }
  }
}

In Claude o ChatGPT, aggiungi lo stesso URL come connettore personalizzato. La scheda del server è disponibile su mcp.financial.md/.well-known/mcp.json e i metadati OAuth su mcp.financial.md/.well-known/oauth-protected-resource.

Inizia con company_lookup, poi usa snapshot_as_of (tutti e tre i prospetti e gli indici, come noti a una data, in una sola chiamata) oppure financials_standardized. Usa verify_value per verificare un numero trovato altrove.

Passaggio 2. Effettua una chiamata API senza chiave

L'API HTTP non richiede né un account né una chiave. Questa chiamata restituisce gli ultimi cinque rendiconti finanziari annuali di Apple, incluso il flusso di cassa libero:

curl "https://api.financial.md/v1/company/financials/cash_flow/standardized?company=ticker:AAPL&period_type=annual&limit=5"

Ogni numero è un oggetto valore con proof.accession, proof.form, proof.filed e proof.source_url (il documento depositato presso la SEC su sec.gov). Aggiungi as_of=2024-06-30 per leggere ciò che era noto a quella data. Verifica un numero confrontandolo con il documento depositato presso la SEC:

curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
  -d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'

Senza chiave, ogni indirizzo IP dispone di 25 chiamate conteggiate al giorno (ratios, screen, verify), 1,000 letture del livello dei documenti depositati presso la SEC e 1,000 letture di metadati. Ogni risposta include intestazioni RateLimit-*; una risposta 429 include Retry-After e il corpo di ogni errore elenca le azioni correttive.

Passaggio 3. Paga per chiamata

agent.financial.md offre le stesse route agli agenti che pagano per chiamata con x402 (USDC su Base), senza account. Una route a pagamento su questo host risponde con 402 e il prezzo in un'intestazione PAYMENT-REQUIRED; firma il pagamento e invia nuovamente la chiamata con un'intestazione PAYMENT-SIGNATURE. Il corpo della risposta 402 indica anche l'host senza chiave, dove la stessa route è gratuita entro i limiti giornalieri.

Il prezzo di ogni route è riportato in pricing.json e nel campo x-price del documento OpenAPI. Il prezzo applicabile è quello nella risposta 402. Una chiamata non riuscita non viene addebitata.

File per agenti

Su cosa può fare affidamento un agente

• Ogni numero ha una fonte: il numero di registrazione del documento depositato presso la SEC, il modulo, la data di deposito, il tag XBRL e un link al documento su sec.gov. GET /proof/{id} mostra i dati grezzi alla base del numero.
• A una certa data (point-in-time): known.from e known.to indicano quando ciascun valore era il dato depositato più recente. as_of, original=true e history=true leggono il passato senza usare informazioni successive e mostrano le rideterminazioni.
• Risposte brevi: una chiamata ai prospetti restituisce solo i periodi richiesti; i risultati degli strumenti MCP iniziano con un riepilogo di una riga prima dei dati strutturati.
• Ticker, CIK o nome: company=ticker:AAPL, company=cik:320193 oppure GET /v1/companies?q=Apple.
• Copertura: società che depositano documenti presso la SEC e sono attualmente quotate su una borsa statunitense; prospetti standardizzati per le società che adottano US GAAP. Solo informazioni, non consulenza in materia di investimenti.