paperclipai/paperclip · error · ToolGatewayHttpError

agent_context_required

agent_context_required

Error message

Paperclip self tools require an agent-scoped gateway session

What it means

paperclip-self tools (like list_my_issues / get_issue_context) are restricted to agent-identified sessions, but the current gateway session has no agentId (e.g. a user/board-issued token). The 403 agent_context_required fires before any self-tool logic runs because there is no 'self' to scope the query to.

Solutions

1. Use an agent-scoped gateway session (agent API key + run context) to call Paperclip self tools.

When it happens

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

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/8001f7d2bfb9256c. Report an issue: GitHub.

Appendix: source

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

          400,
          "Parameters noteId and body are required",
          "invalid_parameters",
        );
      }
      return {
        content: JSON.stringify({ noteId, updated: true }),
        data: {
          noteId,
          bodyLength: body.length,
          transport: "mcp_http",
          spawnedLocalProcess: false,
        },
      };
    }

    if (tool.name === "paperclip-self:list_my_issues") {
      if (!session.agentId) {
        throw new ToolGatewayHttpError(
          403,
          "Paperclip self tools require an agent-scoped gateway session",
          "agent_context_required",
        );
      }
      const limit = Math.max(1, Math.min(50, Number(params.limit ?? 10) || 10));
      const rows = await db
        .select({
          id: issues.id,
          identifier: issues.identifier,
          title: issues.title,
          status: issues.status,
          priority: issues.priority,
        })
        .from(issues)
        .where(
          and(
            eq(issues.companyId, session.companyId),

View on GitHub (pinned to 3f1d897a7c)