cantrip_meter_balance

Check available and reserved credits for your project. Use to monitor usage and manage budgets in cloud-hosted or multi-project environments.

Instructions

Check remaining credits. Returns available credits, reserved credits (held by in-progress operations), and total balance. Pass project to override .cantrip.json — useful in cloud-hosted or multi-project contexts.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project`	No	Project slug — overrides .cantrip.json. Required in environments where cantrip_connect cannot write to the filesystem.

Implementation Reference

src/tools.ts:423-426 (handler)
Handler for cantrip_meter_balance tool - resolves the project and calls client.post('meter', ['balance'], { project }) to check remaining credits
```
handler: async (p) => {
  const project = resolveProject(p.project as string | undefined);
  return client.post("meter", ["balance"], { project });
},
```

src/tools.ts:414-427 (registration)

Full tool definition for cantrip_meter_balance including name, description, schema (projectSchema), and handler

// ── Meter ──
{
  name: "cantrip_meter_balance",
  description:
    "Check remaining credits. Returns available credits, reserved credits (held by in-progress operations), and total balance." +
    PROJECT_DESC_SUFFIX,
  shape: {
    project: projectSchema,
  },
  handler: async (p) => {
    const project = resolveProject(p.project as string | undefined);
    return client.post("meter", ["balance"], { project });
  },
},

src/tools.ts:23-25 (schema)

projectSchema - the input schema used by cantrip_meter_balance (optional string for project slug)

const projectSchema = z.string().optional().describe(
  "Project slug — overrides .cantrip.json. Required in environments where cantrip_connect cannot write to the filesystem.",
);

src/client.ts:36-46 (helper)

resolveProject helper function - resolves project slug from inline parameter or .cantrip.json config file

export function resolveProject(inlineSlug?: string): string {
  if (inlineSlug) return inlineSlug;

  const fromFile = readProjectContext();
  if (fromFile) return fromFile;

  throw new Error(
    "No project context. Either pass the 'project' slug as a parameter, " +
    "or run cantrip_connect first.",
  );
}

src/client.ts:79-125 (helper)

CantripClient.post method - the HTTP client that makes the actual API call to check meter balance

async post(
  command: string,
  args: string[] = [],
  flags: Record<string, string> = {},
): Promise<CantripResponse> {
  const url = `${this.apiUrl}/api/cantrip`;

  // Inject project from .cantrip.json if not provided
  if (!flags.project) {
    const project = readProjectContext();
    if (project) flags.project = project;
  }

  const body: CantripRequest = { command, args, flags };

  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };
  if (this.apiKey) {
    headers["Authorization"] = `Bearer ${this.apiKey}`;
  }

  let res: Response;
  try {
    res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
  } catch (err) {
    throw new Error(
      `Cannot reach Cantrip API at ${this.apiUrl}. ` +
        `Check your network connection and CANTRIP_API_KEY.\n` +
        `(${err instanceof Error ? err.message : String(err)})`,
    );
  }

  const json = (await res.json()) as CantripResponse;
  if ("error" in json && typeof json.error === "string") {
    let message = json.error;
    if (/insufficient credits/i.test(message)) {
      message += "\n\nPurchase credits at https://cantrip.ai";
    }
    if (/not authenticated/i.test(message) || /unauthorized/i.test(message)) {
      message +=
        "\n\nSet CANTRIP_API_KEY in your MCP server config. Get a key at https://cantrip.ai";
    }
    throw new Error(`cantrip error: ${message}`);
  }
  return json;
}

Cantrip