# Costruire un client MCP

Collegare un'applicazione Node.js a FlashData, controllare l'accesso e salvare il primo risultato di ricerca Google.

Riferimento canonico: https://flashdata.dev/it/docs/guides/mcp-custom-client
Recensito: 2026-11-05 da FlashData

<a id="prepare"></a>

## Prima di iniziare

Utilizzare Node.js 22.18+, npm e una chiave API con autorizzazione google_search. La tua applicazione è il client MCP; FlashData ospita il server di https://data.flashdata.dev/mcp. L'esempio controlla la connessione gratuitamente, invia una ricerca con --search e legge il suo risultato salvato con --read.

- [Installare Node.js](https://nodejs.org/en/download)
- [Creare una chiave API](https://flashdata.dev/app/api-keys)
- [Collegare un'app MCP esistente](https://flashdata.dev/it/docs/integrations/mcp-clients/reference.md)

<a id="client"></a>

## 1. Installare il client SDK

Creare un nuovo progetto. Su Windows, utilizzare npm.cmd se npm.ps1 è bloccato.

### Nuovo progetto

```bash
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/sdk@1.30.0
```


<a id="authenticate"></a>

## 2. Impostare il tasto API

Impostare la chiave in questo terminale, o lasciare che il vostro agente inietta FLASHDATA_API_KEY dal suo negozio segreto. Il client lo invia come header X-API-Key al punto finale Streamable HTTP ospitato. Eseguire il codice in un processo locale o server.

### Bash

#### Imposta la chiave

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


### PowerShell 7

#### Imposta la chiave

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```



<a id="client-run"></a>

## 3. Salvare e controllare il client

Salvare il file completo qui sotto come mcp-client.mjs dentro flashdata-mcp-demo, accanto a package.json. Tutti i comandi di questa pagina usano questo file. Scopre strumenti, controlla i prezzi correnti e l'equilibrio, e raccoglie grandi risultati.


<a id="client-source"></a>

### Salvare mcp-client.mjs

#### flashdata-mcp-demo/mcp-client.mjs

```javascript
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'flashdata-first-task', version: '1.0.0' });
const output = 'mcp-search-output';
let searchAttempted = false;
function bodyOf(reply) {
  const body = reply.structuredContent ?? JSON.parse(
    reply.content.filter(item => item.type === 'text').map(item => item.text).join(''));
  if (reply.isError) {
    throw new Error(JSON.stringify({
      code: body.code, http_status: body.http_status, request_id: body.request_id,
    }));
  }
  return body;
}
async function completeResult(reply) {
  let body = bodyOf(reply);
  if (!body.result_id) return body;
  const id = body.result_id;
  let text = body.chunk;
  let offset = body.next_offset;
  while (offset !== null) {
    body = bodyOf(await client.callTool({
      name: 'get_result', arguments: { result_id: id, offset },
    }));
    if (body.result_id !== id || body.offset !== offset ||
        (body.next_offset !== null && body.next_offset <= offset)) {
      throw new Error('Invalid continuation; preserve ' + output + '/mcp-receipt.json.');
    }
    text += body.chunk;
    offset = body.next_offset;
  }
  return JSON.parse(text);
}
function printResult(response, saved = false) {
  if (response.status !== 'done') throw new Error('Search is not done; inspect ' + output + '/result.json.');
  const hits = (response.results ?? []).flatMap(page => page.organic ?? []);
  for (const hit of hits) console.log(hit.title ?? '(no title)', hit.link ?? '(no URL)', hit.snippet ?? '');
  if (!hits.length) console.log('No organic results returned.');
  console.log(saved ? 'Original credits used:' : 'Credits used:', response.usage?.credits ?? 'not reported');
  console.log('Saved response: ' + output + '/result.json');
}
async function main() {
  const mode = process.argv[2] ?? '--check';
  if (process.argv.length > 3 || !['--check', '--search', '--read'].includes(mode)) {
    throw new Error('Usage: node mcp-client.mjs [--check | --search | --read]');
  }
  if (mode === '--read') {
    printResult(JSON.parse(await readFile(output + '/result.json', 'utf8')), true);
    console.log('Local file only. No API call or new charge.');
    return;
  }
  const key = process.env.FLASHDATA_API_KEY?.trim();
  if (!key) throw new Error('Set FLASHDATA_API_KEY in this terminal.');
  await client.connect(new StreamableHTTPClientTransport(
    new URL('https://data.flashdata.dev/mcp'),
    { requestInit: { headers: { 'X-API-Key': key } } },
  ));
  const names = [];
  let cursor;
  do {
    const page = await client.listTools(cursor ? { cursor } : {});
    names.push(...page.tools.map(tool => tool.name));
    cursor = page.nextCursor;
  } while (cursor);
  for (const name of ['google_search', 'get_balance', 'get_pricing']) {
    if (!names.includes(name)) throw new Error('Missing tool: ' + name);
  }
  const balance = bodyOf(await client.callTool({ name: 'get_balance', arguments: {} }));
  const pricing = bodyOf(await client.callTool({
    name: 'get_pricing', arguments: { source: 'google_search', request_count: 1 },
  }));
  const price = pricing.prices.find(p => p.source === 'google_search' && p.available);
  const cost = price?.estimatedCredits;
  if (!Number.isFinite(cost) || cost < 0) throw new Error('No current price; stop here.');
  if (!Number.isFinite(balance.availableCredits)) throw new Error('No current balance; stop here.');
  console.log('Available credits:', balance.availableCredits, 'One search:', cost);
  if (mode === '--check') {
    console.log('Connected. No paid query submitted.');
    console.log(balance.availableCredits >= cost ? 'Ready for one search.' : 'Add credits before searching.');
  } else {
    if (balance.availableCredits < cost) throw new Error('Insufficient credits.');
    // Reserve a new directory before submitting. A repeat run stops here.
    await mkdir(output);
    const request = {
      name: 'google_search',
      arguments: { query: 'battery recycling research', num: 5, mode: 'realtime' },
    };
    await writeFile(output + '/request.json', JSON.stringify(request, null, 2), { flag: 'wx' });
    searchAttempted = true;
    const reply = await client.callTool(request, undefined, { timeout: 120_000 });
    await writeFile(output + '/mcp-receipt.json', JSON.stringify(reply, null, 2), { flag: 'wx' });
    const response = await completeResult(reply);
    await writeFile(output + '/result.json', JSON.stringify(response, null, 2), { flag: 'wx' });
    printResult(response);
  }
}
try {
  await main();
} catch (error) {
  console.error(error instanceof Error ? error.message : String(error));
  if (searchAttempted) console.error('Search was attempted. Preserve saved files and check History before retrying.');
  else console.error('No search submitted by this run.');
  process.exitCode = 1;
} finally {
  await client.close();
}
```


<a id="check-output"></a>

### Controllare la connessione gratuitamente

Eseguire da flashdata-mcp-demo nel terminale in cui si imposta la chiave. Aspettatevi Crediti disponibili, Una ricerca e Collegato. Nessuna domanda pagata presentata. La linea finale dice se il saldo copre una ricerca. Un saldo zero non significa che l'autenticazione sia fallita.

#### In flashdata-mcp-demo

```bash
node mcp-client.mjs
```

- [Controllare i crediti](https://flashdata.dev/app/billing)

<a id="first-task"></a>

## 4. Eseguire la prima ricerca

Utilizza il file salvato nel passaggio 3. La bandiera --search richiede una ricerca Google per la ricerca di riciclaggio della batteria. Il cliente controlla di nuovo il prezzo e l'equilibrio, quindi salva la risposta e stampa i link di origine e i crediti utilizzati.


<a id="submit"></a>

### Invia una ricerca

Esegui una volta da flashdata-mcp-demo. Il client crea mcp-search-output prima di inviare; se quella directory esiste già, si ferma per evitare di ripetere l'attività.

#### In flashdata-mcp-demo

```bash
node mcp-client.mjs --search
```


<a id="result"></a>

### Ispezionare il risultato salvato

Aprire mcp-search-output/result.json. Aspettatevi status: done, results[].organic con titoli, link e snippet, e usage.credits. I risultati organici vuoti possono essere validi. La risposta qui sotto è abbreviata e illustrativa.

#### mcp-search-output/result.json

```json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "http_status": 200,
  "request_id": "example-request-id"
}
```


<a id="read-saved"></a>

### Leggi di nuovo il risultato salvato

Esegui dalla stessa directory di progetto. Questo legge result.json e stampa i link di origine e i crediti originali utilizzati. Non ha bisogno di chiave API, non fa richiesta di rete e non invia un'altra ricerca.

#### In flashdata-mcp-demo

```bash
node mcp-client.mjs --read
```


<a id="saved-files"></a>

## Recuperare un compito interrotto

Mantenere mcp-search-output se una ricerca si ferma prima di stampare i risultati. Una result.json mancante non dimostra che la richiesta non sia riuscita. Ispezionare i file qui sotto e controllare History prima di decidere se è necessario un'altra ricerca.

| File in mcp-search-output | Che cosa ti dice |
| --- | --- |
| request.json | La chiamata di strumento prevista. Salvata prima della presentazione; non conferma che FlashData l'ha ricevuto. |
| mcp-receipt.json | La risposta MCP originale, compresi gli errori o un result_id per la continuazione. Controllare isError e il corpo di risposta; HTTP 200 da solo non è il successo. |
| result.json | La risposta assemblata. Uno stato di fatto è pronto a leggere con --read; preservare request_id per la risoluzione dei problemi. |

- [Richiedi la cronologia](https://flashdata.dev/app/jobs)
- [Dettagli di continuazione](https://flashdata.dev/it/docs/guides/mcp-custom-client/reference.md#continuations)

<a id="continuations"></a>

## Quanti risultati sono raccolti

Il client legge structuredContent, o il testo JSON nel contenuto quando structuredContent è assente. Controlla isError anche quando il trasporto MCP restituisce HTTP 200.

Quando una risposta contiene result_id, completeResult chiama get_result con le stesse credenziali e ha restituito next_offset fino a quando non è null. Controlla la sequenza, concatena i pezzi e analizza il JSON completo. La ricevuta originale rimane in mcp-search-output/mcp-receipt.json.

- [Strumenti e schemi di prosecuzione MCP](https://flashdata.dev/it/docs/mcp/reference.md)

<a id="reuse"></a>

## Utilizzare questo client nella tua applicazione

| Compiti | Cosa cambiare |
| --- | --- |
| Esegui una ricerca diversa | Modificare request.arguments.query e l'output in mcp-client.mjs per una nuova attività. Riutilizzare --read per lo stesso compito completato; mantenere le directory di output precedenti. |
| Lascia che il tuo modello scelga uno strumento | Utilizzare listTools per leggere nomi, descrizioni e schemi di input. Convalida il nome e gli argomenti selezionati, quindi callTool sotto il permesso della tua applicazione e la politica di spesa. |
| Correre su un programma | Riutilizzare una credenziale di proprietà da un deposito segreto persistente. Mantenere un record durevole per slot di pianificazione; leggere l'output salvato quando lo stesso slot si ripete. |
| Collegare altri utenti | Questa chiave addebita l'account del suo proprietario. Utilizzare le credenziali di ogni utente e isolare i risultati salvati. Un'integrazione OAuth ha anche bisogno di una registrazione client, di un consenso e di uno storage token; questo esempio API-chiave non implementa tale flusso. |

- [Attività ricorrenti](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)
- [Opzioni di autenticazione](https://flashdata.dev/it/docs/guides/agent-access/reference.md)

<a id="operate"></a>

## Risoluzione dei problemi

| Problematiche | Azione |
| --- | --- |
| ERR_MODULE_NOT_FOUND | Eseguire l'installazione npm da flashdata-mcp-demo. Tenere mcp-client.mjs accanto a package.json e node_modules. |
| FLASHDATA_API_KEY | Impostare la variabile nello stesso terminale o processo che esegue Node.js, quindi eseguire il nodo mcp-client.mjs senza --search. |
| 401 | Controllare una chiave scaduta o revocata. Ripristinare l'accesso valido, quindi eseguire il controllo della connessione gratuita. |
| 403 | Controlla il permesso google_search e l'accesso all'account. Un controllo di bilancio di successo non dimostra che questa fonte è consentita. |
| 402 / Insufficient credits | Controlla il saldo del conto e i prezzi correnti prima di inviare un'altra attività. |
| EEXIST | Un precedente tentativo possiede la directory di output. Eseguire il nodo mcp-client.mjs --read se result.json è completo; altrimenti ispezionare la ricevuta e History. Tieni la directory. |
| ENOENT / invalido JSON con --read | Controllare che si è in flashdata-mcp-demo e ispezionare mcp-search-output/result.json. Se manca o incompleto, segui Recover a task interrotto; --read non invia mai una ricerca. |
| 429 | Attendere Retry-After quando fornito. Se è stata tentata una ricerca, controllare i file salvati e History prima di riprovare. |
| Timeout / result_unavailable | Tenere la richiesta e la ricevuta. Controllare History o un lavoro esistente; una continuazione salvata potrebbe essere scaduta. |

- [Richiedi la cronologia](https://flashdata.dev/app/jobs)
- [Risoluzione dei problemi MCP](https://flashdata.dev/it/docs/guides/troubleshooting/reference.md#mcp)
