Server MCP

Collega qualsiasi client Model Context Protocol ad Api.Airforce — usa i nostri modelli, le immagini, l’elenco dei modelli e il tuo saldo come strumenti MCP, addebitati sul tuo account.

Che cos’è MCP?

Il Model Context Protocol (MCP) consente ai client di agenti IA — come Claude Desktop, Cursor o qualsiasi app compatibile con MCP — di chiamare servizi esterni come strumenti. Api.Airforce gestisce un server MCP remoto in modo che questi client usino direttamente i nostri modelli.

Endpoint e trasporto

Il server parla JSON-RPC 2.0 su Streamable HTTP su un singolo endpoint, versione del protocollo 2025-06-18. Le risposte in streaming vengono restituite quando invii l’header Accept: text/event-stream.

POST https://api.airforce/mcp

Autenticazione

Invia la tua chiave API Api.Airforce — o un token bearer OAuth 2.0 — nell’header Authorization. Le richieste non autenticate restituiscono 401 con una sfida WWW-Authenticate che punta ai nostri metadati OAuth, così i client conformi avviano automaticamente il flusso OAuth.

Per i token OAuth gli scope rilevanti sono profile (per get_balance), chat (per chat_completion) e images (per generate_image).

Collegare un client

La maggior parte dei client accetta un URL di server MCP remoto più un token bearer. Una configurazione tipica è questa:

{
  "mcpServers": {
    "api-airforce": {
      "url": "https://api.airforce/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Puoi verificare la connessione manualmente con una chiamata JSON-RPC initialize:

curl -X POST https://api.airforce/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'

Strumenti disponibili

Chiama tools/list per scoprirli a runtime. Sono disponibili quattro strumenti:

list_models

Elenca i modelli disponibili con prezzi e flag di capacità.

get_balance

Restituisce il tuo saldo pay-as-you-go (in centesimi di USD) e il piano attuale. Richiede lo scope profile per i token OAuth.

chat_completion

Esegue una chat completion compatibile con OpenAI. Addebitata sul tuo account esattamente come POST /v1/chat/completions.

generate_image

Genera un’immagine. Addebitata sul tuo account esattamente come POST /v1/images/generations.

curl -X POST https://api.airforce/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Fatturazione

chat_completion e generate_image vengono addebitati sul tuo account alle stesse tariffe dell’API REST — non esiste un prezzo MCP separato. list_models e get_balance sono gratuiti.

Discovery

Viene pubblicata una server card leggibile dalla macchina per la scoperta automatica:

https://api.airforce/.well-known/mcp/server-card.json