different-ai/openwork · error

MCP_PROVIDER_TOOL_ERROR

MCP_PROVIDER_TOOL_ERROR

Error message

Inspect the provider operation result and provider logs using the diagnostic reference.

What it means

This is the fallback tool-execution classification: the provider responded with an error that is not invalid-arguments, not 403, and not 429, so the classifier emits provider_tool_error at phase PROVIDER_EXECUTION, non-retryable, owned by the provider admin. It typically represents a provider-side tool error result (e.g. the MCP tool returned isError or the upstream operation failed inside the provider).

Source

Thrown at ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts:1596

          category: "provider_policy_denied",
          code: "MCP_PROVIDER_HTTP_403",
          retryable: false,
          actionOwner: "provider_admin",
          operatorAction: "Grant the provider role, ACL, or application permission required for this operation.",
        }
      : providerStatus === 429
        ? {
            phase: "PROVIDER_EXECUTION",
            category: "provider_throttled",
            code: "MCP_PROVIDER_HTTP_429",
            retryable: true,
            actionOwner: "provider_admin",
            operatorAction: "Wait for the provider rate limit to reset, then retry with bounded backoff.",
          }
        : {
            phase: "PROVIDER_EXECUTION",
            category: "provider_tool_error",
            code: "MCP_PROVIDER_TOOL_ERROR",
            retryable: false,
            actionOwner: "provider_admin",
            operatorAction: "Inspect the provider operation result and provider logs using the diagnostic reference.",
          }
    const classification: Classification = {
      ...classificationBase,
      ...(providerStatus === undefined ? {} : { providerStatus }),
      ...(providerCode ? { providerCode } : {}),
      payloadBytes: evidence.payloadBytes,
      ...(evidence.excerpt ? { providerErrorMessage: evidence.excerpt } : {}),
    }
    logProviderToolEvidence({
      referenceId: this.referenceId,
      evidence,
      diagnosticCode: classification.code,
      ...(providerStatus === undefined ? {} : { providerStatus }),
      ...(providerCode ? { providerCode } : {}),
      ...(requestId ? { providerRequestId: requestId } : {}),

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Inspect the provider operation result payload for the error detail and correlate with provider-side logs using the diagnostic reference.
2. Check the provider's status page/health endpoints for an ongoing incident.
3. Reproduce with a minimal tool call to determine if it's input-specific or a provider fault.
4. Report to the provider admin with the diagnostic reference; retry only after the provider confirms the fault is fixed.

Example fix

// before: blind retry on any tool failure
try { return await callTool(name, args); } catch { return callTool(name, args); }
// after: log diagnostic and surface instead of blind retry
catch (e) { logDiagnostic('MCP_PROVIDER_TOOL_ERROR', e); throw e; }

const health = await fetch(`${providerBase}/healthz`).then(r => r.status);
if (health !== 200) throw new Error(`Provider unhealthy (status ${health}); skipping tool call`);

function isProviderToolError(d: { code: string }): boolean {
  return d.code === 'MCP_PROVIDER_TOOL_ERROR';
}

try { return await callTool(name, args); } catch (e) {
  if (isProviderToolError(e.diagnostic)) { logWithDiagnosticReference(e); notifyProviderAdmin(e.diagnostic); throw e; }
  throw e;
}

When it happens

Trigger: MCP tool call where the provider itself reports the operation failed: the tool returned an error result, the provider's upstream dependency failed, unhandled provider exception (5xx), or malformed provider response that fits no other classification bucket.

Common situations: Provider's backend service down or degraded; provider bug triggered by valid input; provider database/dependency outage; provider returning 500 on a specific resource; tool timing out internally and surfacing an error result.

Related errors

• MCP_PROVIDER_DECLARED_ERROR
• MCP_PROVIDER_INVALID_PARAMS
• MCP_APP_RESOURCE_RESOLUTION_FAILED
• MCP_PROVIDER_INVALID_PARAMS|MCP_PROVIDER_HTTP_403|MCP_PROVIDER_HTTP_429
• invalid_mcp_token_payload

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/e0566e4d53ecd59c. Report an issue: GitHub.