Agentic Scraper Provider SDK for Node.js

Server-side SDK for event-driven MCP Market monetization. Use this package in the MCP or API service you publish as a provider. It is separate from the Agentic Scraper client SDK used by consumers to run agents and automations.

Requires Node.js 18 or newer.

npm install agentic-scraper-provider-sdk

How charging works

For a Marketplace entry configured with provider_event pricing, the Agentic Scraper proxy forwards a signed x-agentic-charge-token header to your service. Your service reports a configured event and count using charge().

For example, an event named tweet-returned can charge once for every tweet that your tool returns. The returned chargedCount is authoritative: it can be lower than the requested count when the buyer's run budget is nearly exhausted.

Express example

import { AgenticProviderClient, getChargeTokenFromHeaders } from 'agentic-scraper-provider-sdk';

const provider = new AgenticProviderClient({ apiKey: process.env.AGENTIC_PROVIDER_API_KEY! });

app.post('/mcp', async (req, res) => {
  const chargeToken = getChargeTokenFromHeaders(req.headers);
  if (!chargeToken) {
    return res.status(400).json({ error: 'Missing Agentic Scraper charge context' });
  }

  const records = await loadRecords();
  const result = await provider.charge({
    chargeToken,
    eventName: 'record-returned',
    count: records.length,
    idempotencyKey: `record-export:${req.body.id}`,
    metadata: { requestedCount: records.length }
  });

  res.json(records.slice(0, result.chargedCount));
});

Fastify handlers can pass request.headers to getChargeTokenFromHeaders() in the same way.

Direct token configuration

You can set a token for one short-lived request scope:

const provider = new AgenticProviderClient({
  apiKey: process.env.AGENTIC_PROVIDER_API_KEY!,
  chargeToken,
});

const result = await provider.charge({
  eventName: 'summary-created',
  idempotencyKey: `summary:${requestId}`,
});

Do not reuse a client-level token between unrelated incoming requests.

Reliability rules

• Pass a stable idempotencyKey for each logical event. Reusing the same run and key returns the original charge instead of charging twice.
• Only return or process result.chargedCount units.
• The SDK retries transport failures, HTTP 429, and 5xx responses up to three times by default and preserves the same idempotency key.
• Validation and other 4xx errors are not retried.
• Verification uses the same charge() method and returns verification: true without debiting a wallet.
• Keep the provider API key and charge token on the server. Never expose or log them.

The default API base URL is https://api.agenticscraper.com/api/v1. Full REST and SDK documentation is available at https://docs.agenticscraper.com.

Fastify handlers use request.headers with getChargeTokenFromHeaders() in the same way. Never log the provider API key or charge token.