Examples: Common Usage Patterns

This guide provides examples for integrating with the Content Intelligence system, covering both the MCP tool interface and the RESTful HTTP API.

MCP Client Usage

The /mcp surface enables LLM agents to perform diagnostic work, triage findings, and query effort predictions.

Connecting a Client

Using the @modelcontextprotocol/sdk TypeScript client to connect to the server:

Predicting Calibrated Effort

Tools use snake_case for arguments. This call fetches a calibrated effort prediction for a specific ticket:

Inspecting Loop Health

Agents can fetch a high-level health overview using the get_health_confidence tool:

HTTP API Usage (/api/v1/ci)

For automated CI/CD checks or reporting dashboards, use the standard RESTful HTTP API.

Initializing the Client

Use the repository's client factory to instantiate an authenticated HTTP client:

Running an Automated Mismatch Analysis

Automated pipelines often verify that current estimates are aligned with historical calibration data before pushing a change:

Checking for Pending Findings

Retrieve all unacknowledged alerts to include in build logs:

Tips for Integration

1. Normalization: The HTTP client automatically handles path encoding and request normalization. You do not need to manually URL-encode organization or loop IDs.
2. Error Handling: Both the MCP tool outputs and the HTTP API return structured error objects. Always check isError in MCP tools or catch ContentIntelligenceApiError instances when using the HTTP client.
3. Authentication: If MCP_BEARER_TOKEN is configured on the server, ensure your HTTP client or MCP transport includes the Authorization: Bearer <token> header in all requests.
4. Health Probes: Use /health/readiness for Kubernetes readiness probes and /health/liveness for basic process monitoring. Use /health/nexus (with auth) to monitor connectivity to the underlying item-store database.