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.

Source

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

              allowStandingDelegation: false, excludeGrantId: original.id,
            });
            const accountId = original.providerTenant?.github?.userId;
            if (!accountId || !alternate.grant
              || alternate.grant.providerTenant?.github?.userId !== accountId
              || alternate.grant.subjectUserId !== original.subjectUserId
              || alternate.grant.subjectAgentId !== original.subjectAgentId) throw error;
            selected = alternate;
          }
        }
        throw new ToolGatewayHttpError(409, "GitHub credentials are unavailable", "github_identity_unavailable");
      }
    }
    return tool;
  }

  function virtualRunToolInput(parameters: unknown): { targetToolName: string; targetParameters: unknown } {
    const params = asRecord(parameters) ?? {};
    const targetToolName = typeof params.tool === "string" ? params.tool.trim() : "";
    if (!targetToolName) {
      throw new ToolGatewayHttpError(400, "run_tool requires a target tool name", "invalid_parameters");
    }
    return {
      targetToolName,
      targetParameters: params.arguments ?? {},
    };
  }

  async function searchableOnDemandTools(session: ToolGatewaySession): Promise<ToolGatewayDescriptor[]> {
    const tools = (await connectedMcpToolsForCompany(session.companyId)).filter(isOnDemandRemoteTool);
    const decisions = await Promise.all(tools.map(async (tool) => ({
      tool,
      decision: await policyService.decide(policyInputForTool({ session, tool })),
    })));
    return decisions
      .filter(({ decision }) => decision.allowed || decision.decision === "require_approval")
      .map(({ tool }) => tool);

View on GitHub (pinned to 01ad858492)

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@01ad858492 (2026-08-18). Data as JSON: /api/errors/8001f7d2bfb9256c. Report an issue: GitHub.