Build a read-only business-metrics tool contract

A read-only metric tool is a safer first MCP exercise than a generic database query. It can expose approved definitions and aggregates while keeping SQL, credentials and row-level data behind the service.

Reconcile a local result

The MCP contract lab sums two synthetic daily order rows.

from mcp_cases import read_metric_case

result = read_metric_case()
assert result["read_only"] is True
assert result["writes"] == 0
assert result["reconciles"] is True
assert result["result"]["value"] == 27
assert result["result"]["unit"] == "count"

The output includes metric, inclusive fixture dates, value, row count, unit and source version. No warehouse or MCP server runs.

Define the metric contract

Accept metric ID, time range and approved dimensions. Enforce maximum range, tenant and roles. Resolve the canonical definition server-side. Return value, unit, window semantics, freshness/source version and useful reason codes.

Avoid raw SQL and arbitrary columns. Limit cardinality and pagination for grouped results. Apply privacy thresholds where small groups could reveal people.

Verify independently

Reconcile fixture results using a second calculation. Test missing dates, incomplete sources, unknown metrics, authorization and zero rows. Log metadata/digests rather than raw records.

The Generative & Agentic AI course uses this contract to connect analytics definitions with MCP and least privilege.

Exercise

Implement three approved metrics over a local database, add tenant/date controls and reconcile every result. Keep the service read-only and inspect its audit events.

Continue learning

This article is part of the MCP and integration contracts sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Design a small MCP tool schema that can be tested.
• Continue with Validate tool output before showing it to a model.

Reference: MCP tools specification.