Error Convention
Every tool returns a JSON string. On failure, the string describes the error in plain language. The MCP transport never sees a raw HTTP status code.
Examples
Validation failed: loan_amount must be greater than 0
Deal not found: 101
Unauthorized: your session has expired. Please sign in again.
Upstream service is temporarily unavailable. Please retry in a few seconds.This shape is deliberate. Models can relay the message back to the user without parsing an envelope, and humans reviewing the transcript see exactly what went wrong.
Internally the server maps backend responses to typed exceptions before serializing: 400/422 → validation, 401 → authentication, 403 → forbidden, 404 → not found, 429 → rate limited, 5xx → server error. Each maps to a distinct human-readable prefix.
Common Errors
Rate Limits
When you hit a rate limit, the error message includes guidance to retry. Back off with jitter; do not retry immediately in a tight loop.
Circuit Breaker
The MCP server protects the Lev backend with a simple circuit breaker in front of every tool call.
If every tool starts returning "Upstream service is temporarily unavailable" at once, the breaker is likely open. Check MCP Health Checks and retry after 30 seconds.
Request Tracing
Every tool call forwards an X-Request-Id UUID to lev-backend. When something surprising happens:
- Note the time of the tool call.
- Share the approximate tool name and timestamp with Lev support.
- Lev will correlate the request ID with backend logs.
Request IDs are not surfaced to the LLM output today. This is intentional — they add tokens without helping the model reason. If you need them exposed for a specific integration, reach out.
Health Checks
The server exposes a health endpoint at /health. It is safe to poll.
curl <mcp-server-url>/health{
"status": "ok",
"version": "0.1.0",
"lev_api": "reachable",
"circuit_breaker": "closed"
}circuit_breaker reports closed, open, or half_open. lev_api reports reachable or degraded based on the last probe. Use these to differentiate between a backend outage and a client-side issue.
Known Gaps
Three lender-discovery tools (search_lenders_for_deal, get_lender_search_results, search_lender_directory) are documented on the MCP Tools page but not yet live. They are being reworked to handle large payloads, MCP-created deal properties, and async ranking signals. get_lender continues to work for direct lookups when a lender_id is known.
If you hit a gap that blocks a real workflow, tell Lev — gaps get prioritized based on real use, not hypothetical needs.