coleam00/Archon · error

❌ Error: ${mcpError.message}

Error message

❌ Error: ${mcpError.message}

What it means

When a Codex MCP tool call reports item.error, streamCodexEvents does not throw; it yields a tool_result with toolOutcome 'error' whose output string is `❌ Error: <mcpError.message>`. The provider forwards the MCP server's own error text to the model as the tool result and logs 'mcp_tool_call_failed' with server, tool, error, and itemId for diagnosis.

Source

Thrown at packages/providers/src/codex/provider.ts:743

          } else {
            getLog().debug({ itemId: item.id, status: item.status }, 'file_change_no_changes');
          }
          break;
        }

        case 'mcp_tool_call': {
          const server = item.server as string | undefined;
          const tool = item.tool as string | undefined;
          const mcpToolName = getMcpToolName(item);

          if ((item.status as string) === 'failed') {
            getLog().warn(
              { server, tool, error: item.error, itemId: item.id },
              'mcp_tool_call_failed'
            );
            const mcpError = item.error as { message?: string } | undefined;
            const errMsg = mcpError?.message
              ? `❌ Error: ${mcpError.message}`
              : '❌ Error: MCP tool failed';
            yield {
              type: 'tool_result',
              toolName: mcpToolName,
              toolOutput: errMsg,
              toolCallId: itemId,
              toolOutcome: 'error',
            };
          } else {
            let toolOutput = '';
            const mcpResult = item.result as { content?: unknown } | undefined;
            if (mcpResult?.content) {
              if (Array.isArray(mcpResult.content)) {
                toolOutput = JSON.stringify(mcpResult.content);
              } else {
                getLog().warn(
                  {
                    itemId: item.id,

View on GitHub (pinned to 0773b97458)

Solutions

1. Check the 'mcp_tool_call_failed' log entry for the full error object, server name, and tool name.
2. Run the MCP server manually with the same arguments to reproduce the tool failure.
3. Verify the MCP server is correctly configured and its dependencies and permissions are in place.
4. Fix the underlying tool or its inputs; the model receives this message as the tool result and can adapt if the text is actionable.

// before the workflow node runs
const serverOk = await spawnMcpServerHealthCheck(declaredMcpServer);
if (!serverOk) throw new Error(`MCP server ${declaredMcpServer.command} failed to start`);

function isMcpToolErrorResult(chunk: unknown): chunk is { type: 'tool_result'; toolOutcome: 'error'; toolOutput: string } {
  const c = chunk as { type?: string; toolOutcome?: string };
  return c?.type === 'tool_result' && c.toolOutcome === 'error';
}

for await (const chunk of stream) {
  if (isMcpToolErrorResult(chunk)) {
    getLog().warn({ tool: chunk.toolName, output: chunk.toolOutput }, 'mcp_tool_failed_downstream');
    // surface to the operator; the model already saw the error text
  }
}

When it happens

Trigger: An MCP server invoked by Codex returns a failed tool call whose error object carries a message: the tool raised an exception server-side, its output was rejected, or the server reported a transport/auth problem for that specific call.

Common situations: MCP tool script exits nonzero or prints an error; the MCP server lacks permissions or files the tool needs; tool arguments rejected by the server's schema; the MCP server crashed mid-call; misconfigured MCP server command in the workflow node's declared MCP config.

Related errors

• ❌ Error: MCP tool failed
• mcp_env_vars_missing
• OpenAI token ${operation} response did not include an id_tok
• MCP config ${fieldPath}.${key} must be a string (got ${descr
• MCP server "${serverName}" must be a JSON object (got ${desc

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/4df9969eebd73d34. Report an issue: GitHub.