API reference

What the tool is and what it takes

The tool's name and description for an agent, the release it serves, how that release measured on its answer key (when it has one), and the JSON Schema of the search request: which filters, exclusions and sorts this tool allows. Doesn't count towards the key's quota.

Search the tool's records

Words, a record to find others like, filters, safety exclusions and sorting, as the tool's schema allows. Exclusions are enforced by the server: a record comes back only if it is known not to have an excluded value, so an unknown value is never treated as safe. Exclusions pinned to the key are always applied as well; a request can only narrow them.

Look up value set entries to filter or exclude by

For a field choosing from a large value set: entries matching some words, by name, synonym or code, so their codes can go in filters and exclusions.

One record by id

A record a search returned, under the same safety exclusions the key applies. One the key's exclusions leave out looks the same as one that doesn't exist.

The tool over MCP

JSON-RPC over Streamable HTTP, with the tool key as a bearer token. tools/list offers search_<name> (the same request as REST search), get_<name>, and find_values when the tool has value set fields. Answers go through the same code as REST, so validation, the safety guarantee and logging are identical. GET and DELETE return 405: there are no sessions.

Body: A JSON-RPC 2.0 request, or a batch.

Read, and build in, the workspace you're building

For your own agent while you build: with a build key (cc_build_…) as a bearer token, it can list datasets and their columns, contracts, readiness, the review queue, receipts, value sets and runs. A key made to build can also create datasets, value sets and fields, edit fields, start runs, and publish when the accuracy gate passes by itself, through the dashboard's checks. Resolving review items, editing stored values, withholding, deleting and publishing past the gate stay with a person.

Body: A JSON-RPC 2.0 request, or a batch.

A result

What each search result, and a single record, looks like.

Webhooks

A POST to your own address when something happens. Every delivery carries the event in CloudCrane-Event, its id in CloudCrane-Delivery (the same on every retry, so you can ignore repeats) and a signature in CloudCrane-Signature. Check the signature before trusting a delivery:

import { createHmac, timingSafeEqual } from "node:crypto";

// header: the CloudCrane-Signature header; body: the raw request body, as received.
export function verify(secret, body, header) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}