Validate identity for an address

Instructions

Implementation Reference

• src/tools/verifications.ts:171-178 (handler)

  Handler function for lob_identity_validation — sends a POST request to Lob's /identity_validation endpoint with the validated args plus optional extra params merged in.

  handler: async (args) => {
    const { extra, ...rest } = args;
    return lob.request({
      method: "POST",
      path: "/identity_validation",
      body: withExtra(rest, extra),
    });
  },

• src/tools/verifications.ts:162-170 (schema)

  Input schema for lob_identity_validation — accepts recipient (required), primary_line (required), optional secondary_line/city/state/zip_code, and an extra escape hatch.

  inputSchema: {
    recipient: z.string().describe("Name to validate."),
    primary_line: z.string(),
    secondary_line: z.string().optional(),
    city: z.string().optional(),
    state: z.string().optional(),
    zip_code: z.string().optional(),
    extra: extraParamsSchema,
  },

• src/tools/verifications.ts:156-179 (registration)

  Registration of the lob_identity_validation tool via registerTool() inside registerVerificationTools(), which is called from registerAllTools() in src/tools/register.ts.

  registerTool(server, {
    name: "lob_identity_validation",
    annotations: { title: "Validate identity for an address", ...ToolAnnotationPresets.read },
    description:
      "Validate a person/business name against a US address. Returns whether the recipient is " +
      "associated with the address.",
    inputSchema: {
      recipient: z.string().describe("Name to validate."),
      primary_line: z.string(),
      secondary_line: z.string().optional(),
      city: z.string().optional(),
      state: z.string().optional(),
      zip_code: z.string().optional(),
      extra: extraParamsSchema,
    },
    handler: async (args) => {
      const { extra, ...rest } = args;
      return lob.request({
        method: "POST",
        path: "/identity_validation",
        body: withExtra(rest, extra),
      });
    },
  });

• src/tools/helpers.ts:85-117 (helper)

  The registerTool helper function that wraps each tool definition (including lob_identity_validation) with error handling and registers it on the MCP server.

  export function registerTool<TShape extends ZodRawShape>(
    server: McpServer,
    def: ToolDefinition<TShape>,
  ): void {
    const a = def.annotations ?? {};
    server.registerTool(
      def.name,
      {
        title: a.title ?? def.name,
        description: def.description,
        inputSchema: def.inputSchema,
        annotations: {
          ...a,
          // Lob is always external; default the hint accordingly.
          openWorldHint: a.openWorldHint ?? true,
        },
      },
      // The SDK's ToolCallback type is parameterised over the exact ZodRawShape and
      // resists the generic erasure here. The runtime contract (validated args in,
      // CallToolResult out) is correct, so we bridge the type boundary with `as never`.
      (async (args: unknown, serverCtx: unknown): Promise<CallToolResult> => {
        try {
          const result = await def.handler(args as never, serverCtx);
          return { content: [{ type: "text", text: stringifyResult(result) }] };
        } catch (err) {
          return {
            isError: true,
            content: [{ type: "text", text: formatErrorForTool(err) }],
          };
        }
      }) as never,
    );
  }