paperclipai/paperclip · error · ToolGatewayHttpError

elicitation_required

elicitation_required

Error message

MCP tool requested additional input

What it means

Elicitation path: the gateway converted an upstream MCP elicitation request into a human interaction card and recorded an elicitation_requested audit event (decision defer_runtime). The 409 tells the agent the tool needs more input; the run should wrap up and wait for the interaction decision rather than retry the call.

Source

Thrown at server/src/services/tool-gateway.ts:3146

        versionSelector: grantRef.versionSelector,
        configPath,
        refHash: credentialVersionRefHash({
          kind: typedRef.placement === "url" ? "url" : "header",
          name: typedRef.name,
          secretId: grantRef.secretId,
          placement: typedRef.placement,
          key: typedRef.key,
          prefix: typedRef.prefix ?? null,
          configPath,
        }),
        requireResolved: options.requireResolved,
      }));
    }

    for (const ref of grant.credentialSecretRefs ?? []) {
      const typedRef = ref as ToolCredentialSecretRef;
      credentialSecretVersions.push(await resolveConnectedCredentialVersion(connection, {
        secretId: typedRef.secretId,
        versionSelector: typedRef.versionSelector,
        configPath: typedRef.configPath,
        refHash: credentialVersionRefHash({
          kind: "secret_ref",
          secretId: typedRef.secretId,
          configPath: typedRef.configPath,
          required: typedRef.required ?? true,
          label: typedRef.label ?? null,
        }),
        requireResolved: options.requireResolved,
      }));
    }

    return { headerCredentialVersions, credentialSecretVersions };
  }

  async function createUserAuthorizationInteraction(
    session: ToolGatewaySession,

View on GitHub (pinned to 01ad858492)

Solutions

1. The MCP tool needs more input (elicitation). Provide the requested fields and retry the call.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:3003 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/3716a24fa559ed69. Report an issue: GitHub.