{
  "serverInfo": {
    "name": "Benefits City",
    "version": "0.3.0"
  },
  "authentication": {
    "required": false,
    "schemes": [],
    "description": "No authentication. Connect to https://aiagentscity.com/benefits/mcp (Streamable HTTP). See https://aiagentscity.com/benefits/auth.md."
  },
  "tools": [
    {
      "name": "search_bonuses",
      "title": "Search bank and credit card signup bonuses",
      "description": "Use when a user wants to find a US bank account, savings, or credit card signup bonus, or asks which offers are worth opening. Returns matching offers sorted by bonus value, highest first.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "bonus_type": {
            "type": "string",
            "enum": [
              "bank_account",
              "credit_card",
              "savings"
            ],
            "description": "Restrict to bank account bonuses, credit card signup bonuses, or savings account bonuses."
          },
          "state": {
            "type": "string",
            "description": "2-letter US state code, e.g. 'TX'. Nationwide offers always match; regional offers match only their states."
          },
          "min_bonus_amount_usd": {
            "type": "number",
            "minimum": 0,
            "description": "Minimum bonus value in USD. For credit cards this is the estimated USD value of the points/miles bonus."
          },
          "direct_deposit_required": {
            "type": "boolean",
            "description": "Filter on whether the bonus requires a qualifying direct deposit."
          },
          "query": {
            "type": "string",
            "description": "Keyword matched against bank/issuer and product name, e.g. 'Chase' or 'Sapphire'."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 25,
            "description": "Max results to return."
          }
        },
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "bonuses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "bank_or_issuer": {
                  "type": "string"
                },
                "product_name": {
                  "type": "string"
                },
                "bonus_type": {
                  "type": "string",
                  "enum": [
                    "bank_account",
                    "credit_card",
                    "savings"
                  ]
                },
                "bonus_amount_usd": {
                  "type": "number"
                },
                "bonus_max_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "bonus_points": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "annual_fee_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "requirements": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "min_deposit_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "direct_deposit_required": {
                  "type": "boolean"
                },
                "expiry_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "states_available": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  ]
                },
                "application_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "last_verified_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "offer_history": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "amount_usd": {
                        "type": "number"
                      },
                      "valid_from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "valid_to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "amount_usd",
                      "valid_from",
                      "valid_to"
                    ],
                    "additionalProperties": false
                  }
                },
                "verification": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "method": {
                          "type": "string",
                          "enum": [
                            "issuer_page",
                            "aggregator_consensus"
                          ]
                        },
                        "verified_at": {
                          "type": "string"
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "method",
                        "verified_at",
                        "sources"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "expired",
                    "needs_review"
                  ]
                },
                "eligibility": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "new_to_bank": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "once_per_lifetime": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "cooldown_months": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "issuer_rules": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "new_to_bank",
                        "once_per_lifetime",
                        "cooldown_months",
                        "issuer_rules"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "sponsored": {
                  "type": "boolean"
                },
                "apply_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "disclosure_url": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "bank_or_issuer",
                "product_name",
                "bonus_type",
                "bonus_amount_usd",
                "bonus_max_usd",
                "bonus_points",
                "annual_fee_usd",
                "requirements",
                "min_deposit_usd",
                "direct_deposit_required",
                "expiry_date",
                "states_available",
                "application_url",
                "source_url",
                "last_verified_date",
                "offer_history",
                "verification",
                "status",
                "eligibility",
                "sponsored",
                "apply_url",
                "disclosure_url"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "bonuses"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "get_bonus",
      "title": "Get one bonus offer in full",
      "description": "Use before recommending an offer, to read its exact requirements, minimum deposit, direct-deposit rules, expiry date, state availability and the date its terms were last verified. Quote the requirements rather than paraphrasing money amounts.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Bonus id, e.g. 'chase-total-checking-400'. Use search_bonuses to find ids."
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "bonus": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "bank_or_issuer": {
                "type": "string"
              },
              "product_name": {
                "type": "string"
              },
              "bonus_type": {
                "type": "string",
                "enum": [
                  "bank_account",
                  "credit_card",
                  "savings"
                ]
              },
              "bonus_amount_usd": {
                "type": "number"
              },
              "bonus_max_usd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "bonus_points": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "annual_fee_usd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "requirements": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "min_deposit_usd": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "direct_deposit_required": {
                "type": "boolean"
              },
              "expiry_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "states_available": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              },
              "application_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "last_verified_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "offer_history": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "amount_usd": {
                      "type": "number"
                    },
                    "valid_from": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "valid_to": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "amount_usd",
                    "valid_from",
                    "valid_to"
                  ],
                  "additionalProperties": false
                }
              },
              "verification": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "method": {
                        "type": "string",
                        "enum": [
                          "issuer_page",
                          "aggregator_consensus"
                        ]
                      },
                      "verified_at": {
                        "type": "string"
                      },
                      "sources": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "method",
                      "verified_at",
                      "sources"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "expired",
                  "needs_review"
                ]
              },
              "eligibility": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "new_to_bank": {
                        "type": [
                          "boolean",
                          "null"
                        ]
                      },
                      "once_per_lifetime": {
                        "type": [
                          "boolean",
                          "null"
                        ]
                      },
                      "cooldown_months": {
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "issuer_rules": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "required": [
                      "new_to_bank",
                      "once_per_lifetime",
                      "cooldown_months",
                      "issuer_rules"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "sponsored": {
                "type": "boolean"
              },
              "apply_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "disclosure_url": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "bank_or_issuer",
              "product_name",
              "bonus_type",
              "bonus_amount_usd",
              "bonus_max_usd",
              "bonus_points",
              "annual_fee_usd",
              "requirements",
              "min_deposit_usd",
              "direct_deposit_required",
              "expiry_date",
              "states_available",
              "application_url",
              "source_url",
              "last_verified_date",
              "offer_history",
              "verification",
              "status",
              "eligibility",
              "sponsored",
              "apply_url",
              "disclosure_url"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "bonus"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "expiring_soon",
      "title": "List bonuses expiring soon",
      "description": "Use when timing matters — a user asking what is about to end, or whether to act now. Offers with no stated end date are never included here.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365,
            "default": 30,
            "description": "Lookahead window in days (default 30)."
          }
        },
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "bonuses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "bank_or_issuer": {
                  "type": "string"
                },
                "product_name": {
                  "type": "string"
                },
                "bonus_type": {
                  "type": "string",
                  "enum": [
                    "bank_account",
                    "credit_card",
                    "savings"
                  ]
                },
                "bonus_amount_usd": {
                  "type": "number"
                },
                "bonus_max_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "bonus_points": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "annual_fee_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "requirements": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "min_deposit_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "direct_deposit_required": {
                  "type": "boolean"
                },
                "expiry_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "states_available": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  ]
                },
                "application_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "last_verified_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "offer_history": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "amount_usd": {
                        "type": "number"
                      },
                      "valid_from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "valid_to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "amount_usd",
                      "valid_from",
                      "valid_to"
                    ],
                    "additionalProperties": false
                  }
                },
                "verification": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "method": {
                          "type": "string",
                          "enum": [
                            "issuer_page",
                            "aggregator_consensus"
                          ]
                        },
                        "verified_at": {
                          "type": "string"
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "method",
                        "verified_at",
                        "sources"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "expired",
                    "needs_review"
                  ]
                },
                "eligibility": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "new_to_bank": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "once_per_lifetime": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "cooldown_months": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "issuer_rules": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "new_to_bank",
                        "once_per_lifetime",
                        "cooldown_months",
                        "issuer_rules"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "sponsored": {
                  "type": "boolean"
                },
                "apply_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "disclosure_url": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "bank_or_issuer",
                "product_name",
                "bonus_type",
                "bonus_amount_usd",
                "bonus_max_usd",
                "bonus_points",
                "annual_fee_usd",
                "requirements",
                "min_deposit_usd",
                "direct_deposit_required",
                "expiry_date",
                "states_available",
                "application_url",
                "source_url",
                "last_verified_date",
                "offer_history",
                "verification",
                "status",
                "eligibility",
                "sponsored",
                "apply_url",
                "disclosure_url"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "bonuses"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "compare_bonuses",
      "title": "Compare 2-4 bonuses side by side",
      "description": "Use when a user is choosing between specific offers. Returns each offer's key fields plus a summary naming the highest bonus and the earliest expiry.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 2,
            "maxItems": 4,
            "description": "2 to 4 bonus ids to compare, e.g. ['chase-total-checking-400', 'sofi-checking-savings-400']."
          }
        },
        "required": [
          "ids"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "bonuses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "bank_or_issuer": {
                  "type": "string"
                },
                "product_name": {
                  "type": "string"
                },
                "bonus_type": {
                  "type": "string",
                  "enum": [
                    "bank_account",
                    "credit_card",
                    "savings"
                  ]
                },
                "bonus_amount_usd": {
                  "type": "number"
                },
                "bonus_max_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "bonus_points": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "annual_fee_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "requirements": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "min_deposit_usd": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "direct_deposit_required": {
                  "type": "boolean"
                },
                "expiry_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "states_available": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  ]
                },
                "application_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "last_verified_date": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "offer_history": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "amount_usd": {
                        "type": "number"
                      },
                      "valid_from": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "valid_to": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "amount_usd",
                      "valid_from",
                      "valid_to"
                    ],
                    "additionalProperties": false
                  }
                },
                "verification": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "method": {
                          "type": "string",
                          "enum": [
                            "issuer_page",
                            "aggregator_consensus"
                          ]
                        },
                        "verified_at": {
                          "type": "string"
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "method",
                        "verified_at",
                        "sources"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "expired",
                    "needs_review"
                  ]
                },
                "eligibility": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "new_to_bank": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "once_per_lifetime": {
                          "type": [
                            "boolean",
                            "null"
                          ]
                        },
                        "cooldown_months": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "issuer_rules": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "new_to_bank",
                        "once_per_lifetime",
                        "cooldown_months",
                        "issuer_rules"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "sponsored": {
                  "type": "boolean"
                },
                "apply_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "disclosure_url": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "bank_or_issuer",
                "product_name",
                "bonus_type",
                "bonus_amount_usd",
                "bonus_max_usd",
                "bonus_points",
                "annual_fee_usd",
                "requirements",
                "min_deposit_usd",
                "direct_deposit_required",
                "expiry_date",
                "states_available",
                "application_url",
                "source_url",
                "last_verified_date",
                "offer_history",
                "verification",
                "status",
                "eligibility",
                "sponsored",
                "apply_url",
                "disclosure_url"
              ],
              "additionalProperties": false
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "highest_bonus_usd": {
                "type": "string"
              },
              "earliest_expiry": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "highest_bonus_usd",
              "earliest_expiry"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "bonuses",
          "summary"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "benefits_api_docs",
      "title": "Read this server's documentation",
      "description": "Use when you need field definitions, ordering guarantees or the error format before calling another tool.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "docs": {
            "type": "string"
          }
        },
        "required": [
          "docs"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    },
    {
      "name": "benefits_examples",
      "title": "Get runnable example calls",
      "description": "Use to copy a working example call instead of guessing tool arguments.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "examples": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "tool": {
                  "type": "string"
                },
                "arguments": {
                  "type": "object",
                  "additionalProperties": {}
                }
              },
              "required": [
                "title",
                "tool",
                "arguments"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "examples"
        ],
        "additionalProperties": false,
        "$schema": "http://json-schema.org/draft-07/schema#"
      },
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "openWorldHint": true
      }
    }
  ],
  "resources": [
    {
      "uri": "skill://benefits-city/benefits-city/SKILL.md",
      "name": "benefits-skill",
      "mimeType": "text/markdown",
      "description": "How to finish the job with Benefits City"
    }
  ]
}