# Bouw een MCP-client

Sluit een Node.js-toepassing aan op FlashData, controleer de toegang en sla uw eerste Google Search-resultaat op.

Canonische referentie: https://flashdata.dev/nl/docs/guides/mcp-custom-client
Beoordeeld: 2026-11-05 door FlashData

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

## Voordat u begint

Gebruik Node.js 22.18+, npm en een API sleutel met google_search toestemming. Uw toepassing is de MCP client; FlashData ondersteunt de server op https://data.flashdata.dev/mcp. Het voorbeeld controleert de verbinding gratis, stuurt een zoekopdracht met --search en leest het opgeslagen resultaat met --read.

- [Node.js installeren](https://nodejs.org/en/download)
- [Een API-sleutel aanmaken](https://flashdata.dev/app/api-keys)
- [Sluit een bestaande MCP-app aan](https://flashdata.dev/nl/docs/integrations/mcp-clients/reference.md)

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

## 1. Installeer de client SDK

Maak een nieuw project aan. Aan WindowsGebruik npm.cmd als npm.ps1 is geblokkeerd.

### Nieuw project

```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. Stel uw API-sleutel in

Stel de sleutel in deze terminal in of laat uw agent FLASHDATA_API_KEY injecteren vanuit zijn geheime opslagruimte. De client stuurt het als een X-API-Key header naar het hosted Streamable HTTP eindpunt. Voer de code uit in een lokaal of server proces.

### Bash

#### Je sleutel instellen

```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

#### Je sleutel instellen

```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. Opslaan en controleren van de client

Sla het volledige bestand hieronder op als mcp-client.mjs in flashdata-mcp-demo, naast package.json. Alle commando's op deze pagina gebruiken dit bestand. Het ontdekt tools, controleert de huidige prijzen en evenwicht, en verzamelt grote resultaten.


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

### mcp-client.mjs opslaan

#### 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>

### Controleer de verbinding gratis

Uitvoeren van flashdata-mcp-demo in de terminal waar u de sleutel hebt ingesteld. Verwacht Beschikbare credits, One search and Connected. Geen betaalde vraag ingediend. De laatste regel zegt of het saldo één zoektocht dekt. Een nulbalans betekent niet dat authenticatie mislukt is.

#### In flashdata-mcp-demo

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

- [Controleer kredieten](https://flashdata.dev/app/billing)

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

## 4. Voer je eerste zoekopdracht uit

Gebruik het bestand dat u in stap 3 hebt opgeslagen. De --search vlag vraagt om één Google zoekopdracht voor batterijrecyclingonderzoek. De klant controleert opnieuw de prijs en het saldo, bespaart vervolgens de respons en drukt de gebruikte bronlinks en credits af.


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

### Een zoekopdracht indienen

Ren één keer van flashdata-mcp-demo. De client maakt mcp-search-output aan voordat deze wordt ingediend; als die directory al bestaat, stopt deze om herhaling van de taak te voorkomen.

#### In flashdata-mcp-demo

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


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

### Het opgeslagen resultaat controleren

mcp-search-output/result.json. openen Verwacht status: done, results[].organic met titels, links en knipsels, en usage.credits. Lege biologische resultaten kunnen geldig zijn. De reactie hieronder is afgekort en illustratief.

#### 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>

### Lees het opgeslagen resultaat opnieuw

Uitvoeren vanuit dezelfde projectmap. Dit leest result.json en drukt de bronlinks en de originele credits af. Het heeft geen API-sleutel nodig, maakt geen netwerkverzoek en stuurt geen andere zoekopdracht.

#### In flashdata-mcp-demo

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


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

## Herstellen van een onderbroken taak

Houd mcp-search-output als een zoekopdracht stopt voordat de resultaten worden afgedrukt. Een ontbrekende result.json bewijst niet dat het verzoek mislukt is. Controleer de onderstaande bestanden en controleer History alvorens te beslissen of een andere zoekopdracht nodig is.

| Bestand in mcp-search-output | Wat het je vertelt |
| --- | --- |
| request.json | Het beoogde gereedschapsgesprek. Opgeslagen voor indiening; het bevestigt niet dat FlashData het ontvangen heeft. |
| mcp-receipt.json | Het originele MCP antwoord, inclusief fouten of een result_id voor voortzetting. Controleer isError en het responslichaam; HTTP 200 alleen is geen succes. |
| result.json | De verzamelde reactie. Een status van gedaan is klaar om te lezen met --read; behoud request_id voor probleemoplossing. |

- [Geschiedenis aanvragen](https://flashdata.dev/app/jobs)
- [Voortzettingsgegevens](https://flashdata.dev/nl/docs/guides/mcp-custom-client/reference.md#continuations)

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

## Hoe groot de resultaten worden verzameld

De client leest structuredContent, of de JSON tekst in inhoud wanneer structuredContent afwezig is. Het controleert isError zelfs wanneer het MCP transport HTTP 200 retourneert.

Wanneer een antwoord result_id bevat, roept completeResult get_result aan met dezelfde credential en gaf next_offset terug tot het null is. Het controleert de volgorde, concateert brokken en ontleedt de volledige JSON. Het originele ontvangstbewijs blijft in mcp-search-output/mcp-receipt.json.

- [MCP-gereedschappen en vervolgschema's](https://flashdata.dev/nl/docs/mcp/reference.md)

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

## Gebruik deze client in uw toepassing

| Taak | Wat te veranderen |
| --- | --- |
| Een andere zoekopdracht uitvoeren | Wijzig request.arguments.query en uitvoer in mcp-client.mjs voor een nieuwe taak. Hergebruik --read voor dezelfde voltooide taak; bewaar eerdere uitvoermappen. |
| Laat uw model een gereedschap kiezen | Gebruik listTools om namen, beschrijvingen en invoerschema's te lezen. Valideer de geselecteerde naam en argumenten, dan callTool onder toestemming van uw toepassing en uitgaven beleid. |
| Uitvoeren op een schema | Hergebruik een eigendomsgetrouwheid uit de permanente geheime opslag. Houd één duurzame record per schema slot; lees opgeslagen uitvoer wanneer dezelfde sleuf herhaalt. |
| Andere gebruikers verbinden | Deze sleutel laadt de rekening van de eigenaar op. Gebruik de eigen geloofwaardigheid van elke gebruiker en isoleer de opgeslagen resultaten. Een OAuth integratie heeft ook een client registratie, toestemming en token opslag nodig; dit API-sleutel voorbeeld implementeert die flow niet. |

- [Terugkerende taken](https://flashdata.dev/nl/docs/guides/recurring-tasks/reference.md)
- [Authenticatieopties](https://flashdata.dev/nl/docs/guides/agent-access/reference.md)

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

## Problemen oplossen

| Probleem | Actie |
| --- | --- |
| ERR_MODULE_NOT_FOUND | Start npm installatie van flashdata-mcp-demo. Houd mcp-client.mjs naast package.json en node_modules. |
| FLASHDATA_API_KEY | Stel de variabele in in dezelfde terminal of hetzelfde proces dat Node.js draait en voer vervolgens knooppunt mcp-client.mjs uit zonder --search. |
| 401 | Controleer op een verlopen of ingetrokken sleutel. Herstellen van geldige toegang, vervolgens opnieuw uitvoeren van de gratis verbinding controle. |
| 403 | Controleer de google_search-machtiging en accounttoegang van de sleutel. Een succesvolle balanscontrole bewijst niet dat deze bron is toegestaan. |
| 402 / Insufficient credits | Controleer rekeningsaldo en actuele prijzen voordat u een andere taak. |
| EEXIST | Een vorige poging bezit de uitvoermap. Voer knooppunt mcp-client.mjs --read uit als result.json voltooid is; inspecteer anders het ontvangstbewijs en History. Hou de directory. |
| ENOENT / ongeldig JSON met --read | Controleer of u in flashdata-mcp-demo bent en inspecteer mcp-search-output/result.json. Als het ontbreekt of onvolledig is, volg Recover een onderbroken taak; --read dient nooit een zoekopdracht in. |
| 429 | Wacht op Retry-After wanneer deze beschikbaar is. Als een zoekopdracht werd geprobeerd, controleer dan de opgeslagen bestanden en History voordat opnieuw te proberen. |
| Tijdslimiet / result_unavailable | Hou het verzoek en de ontvangst. Controleer History of een bestaande taak; een opgeslagen voortzetting kan verlopen zijn. |

- [Geschiedenis aanvragen](https://flashdata.dev/app/jobs)
- [MCP probleemoplossing](https://flashdata.dev/nl/docs/guides/troubleshooting/reference.md#mcp)
