Pagos Data MCP Server

Instructions

Implementation Reference

• main.py:192-206 (handler)

  The core handler function implementing the tool logic: retrieves API key, creates PagosClient, fetches data asynchronously, handles empty response, and formats output.
  async def get_bin_data_tool(bin: str) -> str: """ Get BIN data for a given BIN number. Args: bin (str): The BIN number to get data for. Returns: str: A formatted string containing the BIN data (enhanced or basic based on ENHANCED_BIN_DATA config). """ api_key = os.getenv("PAGOS_API_KEY") pagos_client = PagosClient(api_key=api_key) data = await pagos_client.get_bin_data(bin) if not data: return "Unable to retrieve BIN data or no BIN data found" return format_bin_data(data)
• main.py:191-191 (registration)

  Registers the get_bin_data_tool using the FastMCP tool decorator (@mcp.tool()).
  @mcp.tool()
• main.py:12-189 (helper)

  Supporting function that formats the EnhancedBinApiResponse object into a detailed human-readable string, covering all aspects like card details, product, bank, country, authentication, features, costs, etc.
  def format_bin_data(bin_data: Optional[EnhancedBinApiResponse]) -> str: if not bin_data or not bin_data.card: return "No BIN data available" card = bin_data.card result = [] # Basic card information result.append("Card Details:") result.append("-------------") if card.card_brand: result.append(f"Brand: {card.card_brand}") if card.type: result.append(f"Type: {card.type}") if card.prepaid is not None: result.append(f"Prepaid: {'Yes' if card.prepaid else 'No'}") if card.virtual_card is not None: result.append(f"Virtual Card: {'Yes' if card.virtual_card else 'No'}") if card.funding_source: result.append(f"Funding Source: {card.funding_source}") if card.card_segment_type: result.append(f"Card Segment Type: {card.card_segment_type}") if card.combo_card: result.append(f"Combo Card: {card.combo_card}") # Product information if card.product: result.append("") result.append("Product Information:") result.append("-------------------") if card.product.product_name: result.append(f"Product: {card.product.product_name}") if card.product.product_id: result.append(f"Product ID: {card.product.product_id}") # Bank information if card.bank: result.append("") result.append("Bank Information:") result.append("----------------") if card.bank.name: result.append(f"Bank: {card.bank.name}") if card.bank.clean_name: result.append(f"Clean Name: {card.bank.clean_name}") if card.bank.phone: result.append(f"Phone: {card.bank.phone}") if card.bank.url: result.append(f"URL: {card.bank.url}") # Country information if card.country: result.append("") result.append("Country Information:") result.append("-------------------") if card.country.name: result.append(f"Country: {card.country.name}") if card.country.alpha2: result.append(f"Country Code: {card.country.alpha2}") if card.country.numeric: result.append(f"Numeric Code: {card.country.numeric}") # Authentication information if card.authentication: result.append("") result.append("Authentication:") result.append("---------------") result.append( f"Authentication Required: {'Yes' if card.authentication.authentication_required else 'No'}" ) if card.authentication.authentication_name: result.append( f"Authentication Name: {card.authentication.authentication_name}" ) # Technical details result.append("") result.append("Technical Details:") result.append("-----------------") if card.bin_min and card.bin_max: result.append(f"BIN Range: {card.bin_min} - {card.bin_max}") if card.bin_length: result.append(f"BIN Length: {card.bin_length}") if card.pagos_bin_length: result.append(f"Pagos BIN Length: {card.pagos_bin_length}") if card.number and card.number.length: result.append(f"Card Number Length: {card.number.length}") if card.pan_or_token: result.append(f"PAN or Token: {card.pan_or_token}") if card.correlation_id: result.append(f"Correlation ID: {card.correlation_id}") # Additional features if any( [ card.level2, card.level3, card.alm, card.account_updater, card.domestic_only, card.gambling_blocked, card.reloadable, card.issuer_supports_tokenization, card.shared_bin, ] ): result.append("") result.append("Additional Features:") result.append("-------------------") if card.level2 is not None: result.append(f"Level 2: {'Yes' if card.level2 else 'No'}") if card.level3 is not None: result.append(f"Level 3: {'Yes' if card.level3 else 'No'}") if card.alm is not None: result.append(f"ALM: {'Yes' if card.alm else 'No'}") if card.account_updater is not None: result.append(f"Account Updater: {'Yes' if card.account_updater else 'No'}") if card.domestic_only is not None: result.append(f"Domestic Only: {'Yes' if card.domestic_only else 'No'}") if card.gambling_blocked is not None: result.append( f"Gambling Blocked: {'Yes' if card.gambling_blocked else 'No'}" ) if card.reloadable is not None: result.append(f"Reloadable: {'Yes' if card.reloadable else 'No'}") if card.issuer_supports_tokenization is not None: result.append( f"Issuer Supports Tokenization: {'Yes' if card.issuer_supports_tokenization else 'No'}" ) if card.shared_bin is not None: result.append(f"Shared BIN: {'Yes' if card.shared_bin else 'No'}") # Currency and access information if card.issuer_currency or card.multi_account_access_indicator: result.append("") result.append("Currency & Access:") result.append("------------------") if card.issuer_currency: result.append(f"Issuer Currency: {card.issuer_currency}") if card.multi_account_access_indicator: result.append( f"Multi Account Access: {card.multi_account_access_indicator}" ) # Additional card brands if card.additional_card_brands: result.append("") result.append("Additional Card Brands:") result.append("----------------------") for brand in card.additional_card_brands: if brand.card_brand: result.append(f"- {brand.card_brand}") if brand.card_brand_product: result.append(f" Product: {brand.card_brand_product}") if brand.card_brand_bank_name: result.append(f" Bank: {brand.card_brand_bank_name}") if brand.ecom_enabled is not None: result.append( f" E-commerce Enabled: {'Yes' if brand.ecom_enabled else 'No'}" ) if brand.billpay_enabled is not None: result.append( f" Bill Pay Enabled: {'Yes' if brand.billpay_enabled else 'No'}" ) # Cost information if card.cost and card.cost.interchange: result.append("") result.append("Cost Information:") result.append("-----------------") interchange = card.cost.interchange result.append(f"Regulated: {'Yes' if interchange.regulated else 'No'}") if interchange.regulated_name: result.append(f"Regulated Name: {interchange.regulated_name}") if interchange.notes: result.append(f"Notes: {interchange.notes}") return "\n".join(result)
• pagos_client.py:141-145 (schema)

  Dataclass schema defining the EnhancedBinApiResponse structure used internally for typing and parsing the Pagos API response data.
  class EnhancedBinApiResponse: """Enhanced BIN API response from the Pagos Parrot API.""" card: Optional[EnhancedCard] = None
• pagos_client.py:180-321 (helper)

  PagosClient.get_bin_data async method: constructs API request to Pagos Parrot (/bins), handles HTTP, parses complex nested JSON into dataclasses (EnhancedCard, Bank, etc.), returns typed response or None on error.
  async def get_bin_data( self, bin: str, enhanced: Optional[bool] = None ) -> Optional[EnhancedBinApiResponse]: """ Get BIN data for a given BIN number. Based on the GET /bins endpoint from the Pagos Parrot API. Args: bin: The BIN number to lookup (Bank Identification Number) enhanced: Whether to return enhanced data (default: True) Returns: EnhancedBinApiResponse if successful, None if not found or error occurs Raises: httpx.HTTPStatusError: For HTTP errors (4xx, 5xx) httpx.RequestError: For network/connection errors """ # Use instance setting if enhanced parameter is None enhanced_value = enhanced if enhanced is not None else self.enhanced params = {"bin": bin, "enhanced": str(enhanced_value).lower()} async with httpx.AsyncClient() as client: try: response = await client.get( self.base_url, params=params, headers=self.headers ) response.raise_for_status() data = response.json() # Parse the card data with all enhanced fields card_data = data.get("card", {}) # Parse nested objects number_data = card_data.get("number", {}) number = Number(**number_data) if number_data else None product_data = card_data.get("product", {}) product = Product(**product_data) if product_data else None bank_data = card_data.get("bank", {}) bank = Bank(**bank_data) if bank_data else None country_data = card_data.get("country", {}) country = Country(**country_data) if country_data else None auth_data = card_data.get("authentication", {}) authentication = Authentication(**auth_data) if auth_data else None # Parse cost structure cost_data = card_data.get("cost", {}) cost = None if cost_data: interchange_data = cost_data.get("interchange", {}) interchange = None if interchange_data: domestic_data = interchange_data.get("domestic", {}) domestic = CostDto(**domestic_data) if domestic_data else None inter_data = interchange_data.get("inter", {}) inter = CostDto(**inter_data) if inter_data else None intra_data = interchange_data.get("intra", {}) intra = CostDto(**intra_data) if intra_data else None interchange = Interchange( regulated=interchange_data.get("regulated", False), regulated_name=interchange_data.get("regulated_name"), domestic=domestic, inter=inter, intra=intra, notes=interchange_data.get("notes"), ) cost = Cost(interchange=interchange) # Parse additional card brands additional_brands_data = card_data.get("additional_card_brands", []) additional_card_brands = None if additional_brands_data: additional_card_brands = [ AdditionalNetwork(**brand) for brand in additional_brands_data ] # Parse networkfees networkfees_data = card_data.get("networkfees", {}) networkfees = Networkfees() if networkfees_data else None enhanced_card = EnhancedCard( number=number, bin_length=card_data.get("bin_length"), pagos_bin_length=card_data.get("pagos_bin_length"), bin_min=card_data.get("bin_min"), bin_max=card_data.get("bin_max"), pan_or_token=card_data.get("pan_or_token"), virtual_card=card_data.get("virtual_card"), level2=card_data.get("level2"), level3=card_data.get("level3"), alm=card_data.get("alm"), account_updater=card_data.get("account_updater"), domestic_only=card_data.get("domestic_only"), gambling_blocked=card_data.get("gambling_blocked"), issuer_currency=card_data.get("issuer_currency"), reloadable=card_data.get("reloadable"), additional_card_brands=additional_card_brands, card_brand=card_data.get("card_brand"), card_segment_type=card_data.get("card_segment_type"), combo_card=card_data.get("combo_card"), type=card_data.get("type"), funding_source=card_data.get("funding_source"), prepaid=card_data.get("prepaid"), product=product, bank=bank, country=country, authentication=authentication, cost=cost, networkfees=networkfees, correlation_id=card_data.get("correlation_id"), issuer_supports_tokenization=card_data.get( "issuer_supports_tokenization" ), multi_account_access_indicator=card_data.get( "multi_account_access_indicator" ), shared_bin=card_data.get("shared_bin"), ) return EnhancedBinApiResponse(card=enhanced_card) except httpx.HTTPStatusError as e: # Log the error for debugging print(f"HTTP error {e.response.status_code}: {e.response.text}") return None except httpx.RequestError as e: # Log network/connection errors print(f"Request error: {e}") return None except KeyError as e: # Log data parsing errors print(f"Data parsing error: {e}") return None