different-ai/openwork · error

MCP_PROVIDER_DECLARED_ERROR

MCP_PROVIDER_DECLARED_ERROR

Error message

MCP_PROVIDER_DECLARED_ERROR

What it means

MCP_PROVIDER_DECLARED_ERROR is raised in PROVIDER_EXECUTION phase when the external MCP server itself returned a declared JSON-RPC error. The gateway treats this as a non-retryable, provider-owned failure: the request reached the server and the server deliberately rejected it. The operator is directed to the provider admin because the JSON-RPC error code must be looked up with the provider before correcting the downstream condition.

Source

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

}

function providerAuthorizationClassification(connectUrl: string): Classification {
  return {
    phase: "PROVIDER_AUTHORIZATION",
    category: "provider_authorization_required",
    code: "MCP_PROVIDER_AUTH_REQUIRED",
    retryable: false,
    actionOwner: "member",
    operatorAction: "Connect your account for this provider using its sign-in link, then retry this capability.",
    connectUrl,
  }
}

function providerDeclaredErrorClassification(): Classification {
  return {
    phase: "PROVIDER_EXECUTION",
    category: "provider_declared_error",
    code: "MCP_PROVIDER_DECLARED_ERROR",
    retryable: false,
    actionOwner: "provider_admin",
    operatorAction: "Look up the provider-declared JSON-RPC error code with the provider, then correct the downstream condition and retry.",
  }
}

function safeNativeToken(value: string | undefined, pattern: RegExp, maxLength = 64): string | undefined {
  if (!value || value.length > maxLength || !pattern.test(value)) return undefined
  return value
}

function safeProviderToken(value: unknown, maxLength = 64): string | undefined {
  return typeof value === "string" ? safeNativeToken(value, SAFE_PROVIDER_TOKEN_PATTERN, maxLength) : undefined
}

function safeProviderRequestId(value: unknown): string | undefined {
  return typeof value === "string" ? safeNativeToken(value, SAFE_PROVIDER_REQUEST_ID_PATTERN, 128) : undefined
}

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Read the provider-declared JSON-RPC error code and message from the diagnostic details and look it up in the provider's documentation.
2. Fix the downstream condition it points to (wrong tool arguments, unsupported method, server-side policy) in the caller or provider config.
3. Retry the operation once the condition is corrected; do not blind-retry, this classification is explicitly non-retryable.

Example fix

// before: retrying blindly on any MCP failure
await retry(() => client.callTool({ name: 'search', arguments: { q: 42 } }))
// after: correct the arguments the provider rejected (string expected)
await client.callTool({ name: 'search', arguments: { q: '42' } })

// validate tool arguments against the tool's inputSchema before calling
const parsed = toolInputSchema.safeParse(args)
if (!parsed.success) throw new Error('Invalid tool arguments: ' + parsed.error.message)

function isProviderDeclaredError(d: { code: string; data?: { jsonRpcCode?: number | string } }): boolean {
  return d.code === 'MCP_PROVIDER_DECLARED_ERROR'
}

try {
  await client.callTool({ name, arguments: args })
} catch (e) {
  if (isProviderDeclaredError(e.diagnostic)) {
    // inspect e.diagnostic.data.jsonRpcCode, fix the downstream condition; do NOT retry
    log.error('provider rejected request', e.diagnostic.data?.jsonRpcCode)
  }
  throw e
}

When it happens

Trigger: An MCP tool execution or other JSON-RPC request completes at the HTTP level but the response body contains a JSON-RPC error object with a provider-declared code (e.g. invalid params, method not supported by that server, tool-internal failure). The classifier in external-mcp-diagnostics.ts maps any such declared error to this code via providerDeclaredErrorClassification().

Common situations: Calling a tool with arguments the remote server validates and rejects; invoking a JSON-RPC method the specific MCP server build does not implement; server-side domain rules (quota policy inside the tool, unsupported model name) surfacing as JSON-RPC errors after a provider upgrade or config change.

Related errors

• invalid_jsonrpc_envelope
• jsonrpc_error
• request_id_mismatch
• MCP_INITIALIZE
• MCP_HTTP_404

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