---
id: w8/m2/t004
title: MCP get_usage tool
worker: worker8
status: todo
estimate: 30m
depends_on: [w8/m2/t001]
---

## Objective

Give agents the same read: an MCP `get_usage` tool (workspace month-to-date usage, optional `period`) over the t001 verb — a bex extension (Render's official MCP has no usage tool), serving pillar 3: an agent that deploys services should be able to check what they consume.

## Context

- Per-feature MCP tool registration follows the existing pattern (the MCP server exposes the bex-api verbs; see how `internal/postgres`'s `query_render_postgres` and the apps tools register).
- Tool result: structured JSON matching the REST shape (t003) so agent toolchains see one vocabulary.
- Works over both transports (`/mcp` and `BEX_MCP_STDIO`) for free once registered.

## Steps

1. Define the tool schema (workspace from session context like the other tools; optional `period`).
2. Register it alongside the existing tools; map errors to MCP tool-error shape.
3. Test via the MCP test harness the other tools use.

## Files

- `lego/backend/internal/usage/mcp.go` (+ test), MCP server registration point

## Acceptance criteria

- [ ] `get_usage` is listed by the MCP server and returns the same numbers as REST/GraphQL for the same workspace/month.

## Out of scope

- Render MCP tool-name parity (no equivalent exists — documented in t005).
