4 Upgrades That Transform a Good MCP Server
Into a Production-Ready AI Agent

Structured Error Guidance — Teaching the Agent to Self-Recover

Option A  ·  Agent UX  ·  20+ tool methods enriched

When an AI agent calls an MCP tool and receives an error, it has two options: report the failure to the user, or try to fix it and retry. The difference between those two outcomes often comes down to how much information the error message contains.

A bare "Invalid session token" string leaves the agent with no guidance. But if the same error carries error_type: "authentication_failed" and next_steps: ["Call authenticate() with your username and API key"], the agent can immediately call authenticate() and retry — all without surfacing the failure to the user.

The 7-Type Error Taxonomy

We standardized every tool response around a consistent vocabulary of seven error types, covering the full surface area of failure modes in a real MCP server:

• authentication_failed — expired or invalid session token
• access_denied — connection exists but user lacks permission
• not_found — resource (service, connection, object) doesn't exist
• configuration_error — missing settings or misconfigured server
• validation_error — bad parameter value (out of range, wrong format)
• execution_failed — SQL query failed at runtime
• internal_error — unexpected exception

Context-Aware next_steps

The real value is in next_steps — a JSON array of actionable strings that vary based on context. For execute_query, the guidance changes depending on the result:

// Context-aware next_steps — the agent knows exactly what to do next
NextSteps = rowsReturned == 0
    ? new[]
    {
        "No rows returned — try rephrasing the question with different filters",
        "Call get_schema() to verify table and column names",
        "Call explain_query() to understand why the query returned nothing"
    }
    : totalCount > offset + maxRows
    ? new[]
    {
        $"More rows available — call execute_query() with page={page + 1} to continue",
        "Call analyze_query_results() for an AI summary of these rows",
        "Call execute_query_with_export() to download all pages as CSV/Excel"
    }
    : new[]
    {
        "Call analyze_query_results() to get AI insights on this data",
        "Ask a follow-up question to drill deeper into a specific row or pattern",
        "Call execute_query_with_export() to export the results"
    }

Adding Fields to the Response Model

Every typed response class gets two new optional properties — nullable so existing success responses aren't required to populate them:

public sealed class QueryExecutionResult
{
    [JsonPropertyName("success")]       public bool Success { get; set; }
    [JsonPropertyName("rows")]          public List<Dictionary<string, object?>> Rows { get; set; } = new();
    [JsonPropertyName("total_count")]   public int TotalCount { get; set; }
    // ... other fields ...

    // ── New in this sprint ──
    [JsonPropertyName("error_type")]    public string? ErrorType { get; set; }
    [JsonPropertyName("next_steps")]    public string[]? NextSteps { get; set; }
}