AgentPay-mcp

Instructions

Implementation Reference

• src/tools/session.ts:695-739 (handler)

  The handler function handleX402SessionEnd executes the logic to close a session by ID.

  export async function handleX402SessionEnd(
    input: X402SessionEndInput
  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
    try {
      const lookup = lookupSession(input.session_id);
  
      if (!lookup.found) {
        return {
          content: [
            textContent(`❌ Session not found: "${input.session_id}"`),
          ],
          isError: true,
        };
      }
  
      if (lookup.expired) {
        return {
          content: [
            textContent(
              `ℹ️ Session "${input.session_id}" was already expired.\n` +
              `Endpoint: ${lookup.session.endpoint}`
            ),
          ],
        };
      }
  
      const { session } = lookup;
      endSession(input.session_id);
  
      return {
        content: [
          textContent(
            `✅ **Session Closed**\n\n` +
            `  Session ID: ${session.sessionId}\n` +
            `  Endpoint:   ${session.endpoint}\n` +
            `  Calls made: ${session.callCount}\n\n` +
            `The session has been closed and can no longer be used.\n` +
            `Use x402_session_start to establish a new session when needed.`
          ),
        ],
      };
    } catch (error: unknown) {
      return {
        content: [textContent(formatError(error, 'x402_session_end'))],
        isError: true,

• src/tools/session.ts:668-673 (schema)

  The Zod schema X402SessionEndSchema defines the required input structure (session_id).

  export const X402SessionEndSchema = z.object({
    session_id: z
      .string()
      .uuid()
      .describe('Session ID to close.'),
  });

• src/tools/session.ts:677-693 (registration)

  The x402SessionEndTool object contains the metadata and schema definition for MCP tool registration.

  export const x402SessionEndTool = {
    name: 'x402_session_end',
    description:
      'Explicitly close an x402 V2 session before it expires naturally. ' +
      'After calling this, x402_session_fetch will return an error for the closed session. ' +
      'Useful for security hygiene or when you know a session is no longer needed.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        session_id: {
          type: 'string',
          description: 'Session ID to close (from x402_session_start)',
        },
      },
      required: ['session_id'],
    },
  };