Explorar documentación
Integraciones
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.
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.
# 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: 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 flashdataSecureKey3. 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
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.
node mcp-client.mjs4. 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.
node mcp-client.mjs --searchRevisa 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.
{
"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.
node mcp-client.mjs --readRecupera 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.
| Archivo | Qué contiene |
|---|---|
| request.json | La llamada a la herramienta prevista. Se guarda antes de enviarla; no confirma que FlashData la haya recibido. |
| mcp-receipt.json | La 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.json | La 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
| Tarea | Qué cambiar |
|---|---|
| Ejecutar otra búsqueda | Cambia 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 herramienta | Usa 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ódicas | Reutiliza 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 usuarios | Esta 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
| Problema | Qué hacer |
|---|---|
| ERR_MODULE_NOT_FOUND | Ejecuta npm install desde flashdata-mcp-demo. Mantén mcp-client.mjs junto a package.json y node_modules. |
| FLASHDATA_API_KEY | Define la variable en la misma terminal o proceso que ejecuta Node.js. Después, vuelve a ejecutar node mcp-client.mjs sin --search. |
| 401 | Comprueba si la clave ha caducado o se ha revocado. Restablece un acceso válido y repite la comprobación gratuita de la conexión. |
| 403 | Comprueba 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 credits | Comprueba el saldo y el precio actual antes de enviar otra tarea. |
| EEXIST | El 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 --read | Comprueba 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. |
| 429 | Espera 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_unavailable | Conserva request.json y mcp-receipt.json. Revisa History o el trabajo existente; el resultado guardado para recuperar más fragmentos puede haber caducado. |