Saltar al contenido
ES
Obtener clave API
Explorar documentación

Integraciones

Crea un cliente MCP

Conecta una aplicación de Node.js a FlashData, comprueba el acceso y guarda el resultado de tu primera búsqueda en Google Search.

En esta página

Antes de empezar

Necesitas Node.js 22.18+, npm y una clave API con permiso google_search. Tu aplicación actúa como cliente MCP; FlashData aloja el servidor en https://data.flashdata.dev/mcp. Este ejemplo comprueba la conexión gratis, envía una búsqueda con --search y lee el resultado guardado con --read.

1. Instala el SDK del cliente

Crea un proyecto nuevo. En Windows, usa npm.cmd si npm.ps1 está bloqueado.

Nuevo proyecto
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]

2. Configura tu clave API

Configura la clave en esta terminal o deja que tu agente defina FLASHDATA_API_KEY desde su almacén de secretos. El cliente la envía en la cabecera X-API-Key al endpoint Streamable HTTP de FlashData. Ejecuta el código en un proceso local o en el servidor.

Configura la clave
# 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

3. Guarda y comprueba el cliente

Guarda el archivo completo que aparece a continuación como mcp-client.mjs dentro de flashdata-mcp-demo, junto a package.json. Todos los comandos de esta página usan ese archivo. El cliente descubre las herramientas, consulta el precio y el saldo actuales y recupera los resultados grandes.

Guarda mcp-client.mjs

flashdata-mcp-demo/mcp-client.mjs
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();
}

Comprueba la conexión gratis

Ejecuta el comando desde flashdata-mcp-demo, en la terminal donde configuraste la clave. Verás «Available credits», «One search» y «Connected. No paid query submitted.». La última línea indica si el saldo cubre una búsqueda. Un saldo de cero no significa que haya fallado la autenticación.

En flashdata-mcp-demo
node mcp-client.mjs

4. Ejecuta tu primera búsqueda

Usa el archivo que guardaste en el paso 3. La opción --search solicita una búsqueda en Google de battery recycling research. El cliente vuelve a comprobar el precio y el saldo, guarda la respuesta y muestra los enlaces de las fuentes y los créditos utilizados.

Envía una búsqueda

Ejecuta el comando una vez desde flashdata-mcp-demo. El cliente crea mcp-search-output antes de enviar la solicitud. Si ese directorio ya existe, se detiene para evitar repetir la tarea.

En flashdata-mcp-demo
node mcp-client.mjs --search

Revisa el resultado guardado

Abre mcp-search-output/result.json. Comprueba status: done, results[].organic con títulos, enlaces y fragmentos, y usage.credits. Una lista vacía de resultados orgánicos puede ser válida. La respuesta siguiente es un ejemplo abreviado.

mcp-search-output/result.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"
}

Vuelve a leer el resultado guardado

Ejecuta el comando desde el mismo directorio del proyecto. Lee result.json y muestra los enlaces de las fuentes y los créditos utilizados originalmente. No requiere clave API, no hace solicitudes de red ni envía otra búsqueda.

En flashdata-mcp-demo
node mcp-client.mjs --read

Recupera una tarea interrumpida

Conserva el directorio mcp-search-output si la búsqueda se interrumpe antes de mostrar los resultados. Que falte result.json no demuestra que la solicitud haya fallado. Revisa estos archivos y History antes de decidir si necesitas otra búsqueda.

ArchivoQué contiene
request.jsonLa llamada a la herramienta prevista. Se guarda antes de enviarla; no confirma que FlashData la haya recibido.
mcp-receipt.jsonLa respuesta MCP original, incluidos los errores o un result_id para recuperar los siguientes fragmentos. Comprueba isError y el cuerpo de la respuesta; HTTP 200 por sí solo no confirma el éxito.
result.jsonLa respuesta completa. Si status es done, puedes leerla con --read. Conserva request_id para diagnosticar problemas.

Cómo se recuperan los resultados grandes

El cliente lee structuredContent o, si no existe, el texto JSON de content. Comprueba isError incluso cuando el transporte MCP devuelve HTTP 200.

Si la respuesta contiene result_id, completeResult llama a get_result con la misma credencial y el next_offset recibido, hasta que next_offset sea null. Verifica el orden, une los fragmentos e interpreta el JSON completo. La respuesta original se conserva en mcp-search-output/mcp-receipt.json.

Usa este cliente en tu aplicación

TareaQué cambiar
Ejecutar otra búsquedaCambia request.arguments.query y la variable output en mcp-client.mjs para una tarea nueva. Usa --read para releer la misma tarea completada y conserva los directorios de resultados anteriores.
Dejar que el modelo elija una herramientaUsa listTools para consultar los nombres, las descripciones y los esquemas de entrada. Valida el nombre y los argumentos elegidos antes de usar callTool, según los permisos y la política de gasto de tu aplicación.
Programar tareas periódicasReutiliza una credencial del titular guardada en un almacén de secretos persistente. Conserva un registro duradero por cada ejecución programada. Si se repite la misma ejecución, lee el resultado guardado.
Conectar a otros usuariosEsta clave consume créditos de la cuenta de su titular. Usa la credencial de cada usuario y separa sus resultados guardados. Una integración OAuth también requiere registrar un cliente, obtener consentimiento y almacenar tokens; este ejemplo con clave API no implementa ese flujo.

Solución de problemas

ProblemaQué hacer
ERR_MODULE_NOT_FOUNDEjecuta npm install desde flashdata-mcp-demo. Mantén mcp-client.mjs junto a package.json y node_modules.
FLASHDATA_API_KEYDefine la variable en la misma terminal o proceso que ejecuta Node.js. Después, vuelve a ejecutar node mcp-client.mjs sin --search.
401Comprueba si la clave ha caducado o se ha revocado. Restablece un acceso válido y repite la comprobación gratuita de la conexión.
403Comprueba el permiso google_search de la clave y el acceso a la cuenta. Poder consultar el saldo no confirma que tengas acceso a esta fuente.
402 / Insufficient creditsComprueba el saldo y el precio actual antes de enviar otra tarea.
EEXISTEl directorio de resultados pertenece a un intento anterior. Si result.json está completo, ejecuta node mcp-client.mjs --read. Si no, revisa mcp-receipt.json y History. Conserva el directorio.
ENOENT / JSON no válido con --readComprueba que estás en flashdata-mcp-demo y revisa mcp-search-output/result.json. Si falta o está incompleto, sigue «Recupera una tarea interrumpida». --read nunca envía una búsqueda.
429Espera el tiempo indicado en Retry-After, si se incluye. Si ya intentaste una búsqueda, revisa los archivos guardados y History antes de reintentar.
Tiempo de espera agotado / result_unavailableConserva request.json y mcp-receipt.json. Revisa History o el trabajo existente; el resultado guardado para recuperar más fragmentos puede haber caducado.