Tool Router

The Tool Router is the layer that turns a CodeSpar session into a live tool-access endpoint. Once a session exists, your agent can:

• Execute registered tools via session.execute(tool, params) — the standard path for anything in the catalog.
• Proxy raw HTTP calls via session.proxyExecute(...) — for endpoints that don't have a pre-defined tool yet, or when you need provider-specific fields the meta-tools don't expose.
• Stream as MCP — the session URL is consumable by any MCP-compatible client (Claude Desktop, Cursor, VS Code).

In every case, credentials stay on the server. Your agent sees only the session id; the backend injects the right API key, OAuth token, or certificate per provider and logs the call.

Why a router

Most commerce workflows touch 3–6 providers. Without a router, each call forces the agent code to:

1. Hold the provider credential (security and compliance headache).
2. Format the request in the provider's native shape.
3. Handle rate limits, retries, and credential rotation per provider.
4. Log, audit, and bill the call manually.

With the router, the agent holds one short-lived CodeSpar API key, calls session.execute or session.proxyExecute, and the backend takes care of the rest.

Three ways to call a tool

1. Meta-tool (the default)

const result = await session.execute("codespar_pay", {
  method: "pix",
  amount: 15000,
  currency: "BRL",
  customer: { doc: "12345678900", name: "Maria" },
});

Meta-tools (codespar_pay, codespar_invoice, codespar_ship, codespar_notify, codespar_checkout, codespar_discover) route to the best provider for the region and payment method. Agent doesn't need to know whether the Pix went through Asaas, Zoop, or Mercado Pago — the router picks.

2. Raw provider tool

const result = await session.execute("STRIPE_CREATE_CHARGE", {
  amount: 1000,
  currency: "usd",
  source: "tok_visa",
});

Use when the meta-tool abstraction is too loose and you want the provider's exact field shape. Credentials still injected server-side.

3. Proxy execute (raw HTTP)

const result = await session.proxyExecute({
  server: "stripe",
  endpoint: "/v1/charges",
  method: "POST",
  body: {
    amount: 1000,
    currency: "usd",
    source: "tok_visa",
  },
});

if (result.status === 201) {
  console.log("charge id:", (result.data as { id: string }).id);
}

For anything not yet covered by a registered tool — new provider endpoints, beta APIs, or one-off integrations. The backend still injects auth for the named server, rate-limits, and writes an audit log.

Request shape

interface ProxyRequest {
  server: string;                 // e.g. "stripe", "asaas"
  endpoint: string;               // e.g. "/v1/charges"
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  body?: unknown;                 // JSON body (ignored for GET)
  params?: Record<string, string | number | boolean>;  // query string
  headers?: Record<string, string>;  // request metadata — NOT auth
}

Response shape

interface ProxyResult {
  status: number;                     // upstream HTTP status
  data: unknown;                      // parsed JSON, or string if non-JSON
  headers: Record<string, string>;    // response headers, lowercased
  duration: number;                   // upstream call duration (ms)
  proxy_call_id?: string;             // log cross-reference id
}

On a non-2xx backend response (your session expired, the server isn't connected, rate limit), proxyExecute throws. The status field on the result object is the upstream status — a proxied 401 from Stripe is a successful proxy call that returned 401.

MCP endpoint

Every session exposes an MCP-compatible URL via session.mcp:

const { url, headers } = session.mcp;
// Plug into Claude Desktop, Cursor, VS Code, or any MCP client.

Helpers in @codespar/mcp generate the right config file for each client.

Observability

Every call through the router — execute, proxyExecute, and MCP-routed calls — is logged with:

• The session id, user id, and org id
• The tool or endpoint called and the parameters
• Upstream latency, status, and byte count
• Retry attempts and final outcome

Stream logs live with codespar logs tail or the backend GET /v1/logs/stream SSE endpoint.

Next steps

• Sessions — how a session is created and managed
• Authentication — Connect Links and provider OAuth
• Tools — the 6 meta-tools and raw provider catalogs