Ejemplos de código

Clientes listos para copiar y pegar para ambos transportes del contrato de lectura de IRIS. Reemplaza la clave de marcador de posición iris_xxx con tu clave emitida por el operador en tiempo de ejecución — nunca subas una clave real.

REST

curl

export IRIS_BASE_URL="https://<iris-host>"
export IRIS_API_KEY="iris_xxx"

# Search/list brand summaries (keyset page)
curl -sS "$IRIS_BASE_URL/v1/brands?q=cafe&limit=5" \
  -H "X-API-Key: $IRIS_API_KEY"

# Full detail for one application number
curl -sS "$IRIS_BASE_URL/v1/brands/123456" \
  -H "X-API-Key: $IRIS_API_KEY"

TypeScript (fetch)

const baseUrl = process.env.IRIS_BASE_URL!;
const apiKey = process.env.IRIS_API_KEY!; // "iris_xxx"

async function searchBrands(q: string, limit = 20) {
  const url = new URL(`${baseUrl}/v1/brands`);
  url.searchParams.set("q", q);
  url.searchParams.set("limit", String(limit));

  const res = await fetch(url, { headers: { "X-API-Key": apiKey } });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${res.status} ${error.code}: ${error.message}`);
  }
  return res.json() as Promise<{ items: unknown[]; nextCursor: string | null }>;
}

const page = await searchBrands("cafe", 5);
console.log(page.items.length, "results; nextCursor =", page.nextCursor);

MCP

Un cliente mínimo de @modelcontextprotocol/sdk que se conecta al endpoint Streamable HTTP con el encabezado X-API-Key y luego llama a ambas herramientas. Esto replica la prueba de humo sobre el cable en deploy/smoke/mcp-smoke.ts, recortada a un ejemplo de connect + callTool.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const url = process.env.MCP_URL ?? "https://mcp.obviouy.com";
const apiKey = process.env.IRIS_API_KEY!; // "iris_xxx"

// The X-API-Key header is attached to every transport request via requestInit.
const transport = new StreamableHTTPClientTransport(new URL(url), {
  requestInit: { headers: { "X-API-Key": apiKey } },
});

const client = new Client({ name: "iris-mcp-example", version: "1.0.0" });
await client.connect(transport); // runs the JSON-RPC initialize handshake

try {
  // search_brands — same input + output as REST GET /v1/brands
  const search = await client.callTool({
    name: "search_brands",
    arguments: { q: "cafe", limit: 5 },
  });
  // Tool payloads come back as a JSON string in the first text content block.
  const firstText = (r: typeof search) =>
    (r.content as Array<{ type: string; text?: string }>).find((c) => c.type === "text")?.text;
  const page = JSON.parse(firstText(search) ?? "{}");
  console.log(page.items.length, "results; nextCursor =", page.nextCursor);

  // get_brand_detail — same input + output as REST GET /v1/brands/:nroSolicitud
  const detail = await client.callTool({
    name: "get_brand_detail",
    arguments: { nroSolicitud: "123456" },
  });
  console.log(firstText(detail)); // full detail JSON, or "null" when unknown
} finally {
  await client.close();
}

Ambas herramientas requieren el scope brands:read (o una clave sin restricción, con scopes vacíos). Una clave ausente o inválida hace que la llamada a herramienta devuelva un resultado de error — nunca datos del corpus. Consulta la guía de MCP y la guía de autenticación.

Ver también

• Primeros pasos — puesta en marcha de REST y paginación.
• Conecta tu agente de IA (MCP) — endpoint, herramientas, configuración de cliente.
• La referencia OpenAPI en vivo en /docs — el esquema REST autoritativo.