flatin.pt — Portuguese homes: new-builds, places, taxes

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Portugal home buying: new-build search, where-to-live guides, municipality data, IMT/IMI taxes

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "flatin.pt — Portuguese homes: new-builds, places, taxes": {
      "url": "https://flatin.pt/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (12)

• imt_calculate read-only

  Calculates the one-off taxes of buying a home in Portugal: IMT, stamp duty and the Casa Pronta registration price, by the official 2026 tables. Use it for the cost on top of the price; for the yearly property tax use `imi_annual_cost`, and to explain a term such as VPT `glossary_lookup`. Both taxes are charged on the higher of `value` and `vpt`: pass the VPT when known. `tax_haven_company` takes precedence over `non_resident`. `buyer_is_young` applies only when `primary_home` is true. For a non-resident buyer the answer says what the Tax Authority annuls later on request.

  Parameters:

  • value (required) — string — Purchase price as written in the contract, in euros; a dot or a space may group thousands (250.000)
  • vpt — string — Optional. The VPT (valor patrimonial tributário) from the caderneta predial, in euros. IMT and stamp duty are charged on the higher of the price and the VPT (CIMT art. 12.º n.º 1), so pass it when it is known
  • territory — string — Mainland Portugal (continente) or the Azores and Madeira (regioes_autonomas), which have their own IMT tables
  • non_resident — boolean — The buyer is not and has never been tax resident in Portugal. IMT is then a flat rate with no exemption or reduction — no zero band, no young buyers' table, no stamp duty deduction (CIMT art. 17.º n.º 10); the result says what the Tax Authority annuls on request if the buyer becomes tax resident or lets the home at a moderate rent. A buyer who has already been treated as tax resident pays by the tables: leave it false
  • primary_home — boolean — The buyer's own permanent home (habitação própria e permanente); false for a second home or an investment, which has no zero band
  • buyer_is_young — boolean — The buyer is 35 or under on the date of the deed, is buying their first own permanent home, is not an IRS dependant and has owned no residential property in the previous three years. Applies the reduced IMT table and the stamp duty deduction (art. 7.º-A Código do Imposto do Selo; not applied above the second band of the young buyers' table). Only applies when primary_home is true; with primary_home false it is ignored
  • tax_haven_company — boolean — The buyer is a company or other entity with its tax domicile in a country, territory or region on the Portuguese list of more favourable tax regimes, or controlled directly or indirectly by such an entity. IMT is then 10 % with no exemption or reduction (CIMT art. 17.º n.º 4), whether or not it is resident, and it overrides non_resident. Never true for an individual (n.º 7)

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• imi_rate read-only

  Looks up the yearly IMI (municipal property tax) rate of one Portuguese municipality, by name or four-digit code, with its history by year. Use it when only the rate is needed; for the yearly amount on a given VPT use `imi_annual_cost`, and for several municipalities side by side `compare_municipalities`. Rates come from the Autoridade Tributária portal, checked for all 308 municipalities. Where the rate is set per parish, the answer says so instead of giving a number.

  Parameters:

  • municipality (required) — string — Municipality name (Porto, Lisboa or Lisbon, Vila Nova de Gaia) or its four-digit code (1312)

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• imi_annual_cost read-only

  Calculates the yearly IMI on an urban property (prédio urbano) from its taxable value (VPT) and the urban rate of its municipality. Use it for the yearly amount; for the rate alone use `imi_rate`, and for the one-off purchase taxes `imt_calculate`. The VPT is the Tax Authority's valuation on the caderneta predial, not the purchase price: ask the user for it rather than using the price. Only the urban rate is applied; rural property, AIMI and surcharges on vacant homes are not calculated. A municipality whose rate is set per parish is refused (rate_by_freguesia).

  Parameters:

  • municipality (required) — string — Municipality name (Porto, Lisboa or Lisbon, Vila Nova de Gaia) or its four-digit code (1312)
  • vpt (required) — string — Valor Patrimonial Tributário — the taxable value of the property in euros, from the caderneta predial. Not the purchase price

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• request_consultation

  Sends the person's request to buy a new-build apartment in Portugal to flatin.pt (licensed estate agency, AMI 28163), only with their explicit consent. Use it when the person wants to be contacted; for emails about new projects use `subscribe_digest`. mode=link only returns the form link and the consent text. mode=prepare checks the details and returns a summary, the GDPR (RGPD) consent text and a confirmation_token; neither sends anything. Show the person the summary and the consent text word for word; only if they explicitly agree, call mode=submit with the same details, the token, consent=true and consent_text_version. Never set consent=true on your own. Changed details, a token younger than 5 seconds or older than 30 minutes, or an outdated consent version are refused. A submit that goes through returns status received.

  Parameters:

  • city — string — Older name for places: one place. Merged with places, city first
  • mode — string — link: only the form link and the consent text. prepare: check the details, get a summary, the consent text and a confirmation_token; nothing is sent. submit: send the request — the same details as in prepare plus confirmation_token, consent=true and consent_text_version, only after the person has read the consent text and explicitly agreed
  • name — string — The person's name
  • email — string — Only if the person gives no phone
  • phone — string — Phone in international format. Preferred over email
  • budget — integer — Deprecated: use budget_max. Read as budget_max when budget_min and budget_max are both empty
  • client — string — Optional. Your app's host or name: recorded as the request's source
  • intent — string — Optional. visit and reserve only with a project on sale, notify only with a project not yet on sale
  • places — array — Where the person wants to buy: municipalities in Portugal (Lisboa or Lisbon) or districts, most important first. At least one place, unless project is given (the project's municipality comes first then)
  • channel — string — How the person wants to be contacted on that phone
  • consent — boolean — submit only: true once the person has read the consent text returned by prepare and explicitly agreed
  • message — string — Optional. The person's own words
  • project — string — Optional. Slug of the development the request is about: the slug field of search_newbuilds
  • language — string — The person's language: the consent text, the emails and the page links come in it. Another value is refused, except in mode=link, which falls back to English. uk is accepted as ua.
  • typology — array — Optional. Bedroom counts wanted (T2 = two bedrooms)
  • deal_type — string — Deprecated and ignored: every request is to buy
  • budget_max — integer — Optional. Upper end of the budget in whole euros; if lower than budget_min, the two are swapped
  • budget_min — integer — Optional. Lower end of the budget in whole euros
  • budget_band — string — Deprecated: use budget_min and budget_max. An old band (0-250k, 250-400k, 400-600k, 600k+), read as its range when both are empty
  • property_type — string — Deprecated and ignored: every request is for a new-build apartment
  • preferred_time — string — Optional, with intent=visit: when suits the person
  • confirmation_token — string — submit only: the token returned by prepare
  • consent_text_version — string — submit only: consent_text_version returned by prepare

  Hints: read-only no · destructive no · idempotent yes · open-world yes

• subscribe_digest

  Subscribes the person's email to new-build projects matching a filter (daily) or to new construction licensed in one municipality (weekly), by double opt-in. Use it when the person asks to be told about new projects; to have flatin.pt contact them use `request_consultation`, and to see what is on sale now `search_newbuilds`. Ask the person first: it only sends a confirmation email, and nothing is active until they click its link. `city` is required for construction and `parish` works only there; `typology`, the prices and `on_sale` work only with new_developments. The answer is the same whether or not the address was already subscribed: never tell the person they were.

  Parameters:

  • email (required) — string — The person's email address
  • city — string — Municipality (Lisboa or Lisbon). Required for construction; empty means all of Portugal for new_developments
  • what — string — new_developments: new-build developments matching the filter, daily email when something new appears. construction: newly licensed construction in a municipality ("what is being built"), weekly
  • client — string — Optional. Your app's host or name: recorded as the request's source
  • parish — string — Optional, construction only: a parish (freguesia) of that municipality
  • on_sale — boolean — Optional, new_developments: only developments on sale
  • language — string — The person's language: the consent text and the emails come in it. uk is accepted as ua.
  • typology — array — Optional. Bedroom counts wanted (T2 = two bedrooms)
  • price_max — integer — Optional, new_developments: maximum price in euros
  • price_min — integer — Optional, new_developments: minimum price in euros

  Hints: read-only no · destructive no · idempotent yes · open-world yes

• where_to_live read-only

  Gives a flatin.pt city guide's verdict on where to live, area by area, with the reason, who each area suits and the sources. Use it to choose a neighbourhood; for one municipality's figures use `municipality_stats`, and for new homes there `search_newbuilds`. Without `city` it lists the cities and regions that have a guide. `profile` narrows the areas but never hides the ones we advise against. Noise and safety come as dated, sourced facts: a place's reputation, never a claim about its people. Show the guide's link to the user.

  Parameters:

  • city — string — City or region with a guide, in any site language (Porto, Lisbon, Lisboa, Greater Porto, Algarve, Coimbra) or a municipality inside a guide (Gaia, Cascais, Faro). Omit to list the guides
  • include — array — Parts of the guide to return; all returns every section
  • profile — string — Keep the areas that suit this profile; profile never removes the areas we advise against
  • verdict — string — Keep only areas with this verdict: live (good to live), depends (depends on you), avoid (we advise against)
  • language — string — Language of the answer: the guide or the definition, the text summary and the page links. Field names stay English. uk is accepted as ua.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• municipality_stats read-only

  Returns the key figures of one of Portugal's 308 municipalities, with the source and date of each official figure. They are the IMI rate and history, INE median sale price per m² (actual sales, not asking prices), purchasing power, population, licensed new dwellings, building-works cases and our new-build count. Use it for one municipality; to compare two to five use `compare_municipalities`, for areas inside a city `where_to_live`, and for building activity by month `construction_barometer`. A figure that is not published is null, not estimated. A name matching two municipalities is refused with candidates.

  Parameters:

  • municipality (required) — string — Municipality name in any case, accents optional (Porto, Lisboa, Vila Nova de Gaia, Matosinhos; Lisbon and Oporto are accepted) or its four-digit code (1312). Close spellings are found; two matches return an `ambiguous` error with candidates
  • language — string — Language of the page links and labels; the text summary and field names stay English. uk is accepted as ua.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• compare_municipalities read-only

  Compares two to five Portuguese municipalities side by side, with the same figures for each as `municipality_stats`. Use it when choosing between places; for a single municipality use `municipality_stats`, and for the areas inside one city `where_to_live`. Names that point at the same municipality count once, and fewer than two distinct ones are refused (bad_count). One unknown or ambiguous name refuses the whole comparison.

  Parameters:

  • municipalities (required) — array — Two to five municipality names or codes
  • language — string — Language of the page links and labels; the text summary and field names stay English. uk is accepted as ua.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• construction_barometer read-only

  Reports how much is being built in Portuguese municipalities. It gives flatin.pt's monthly count of building-works cases entering licensing, for the municipalities we collect, and INE's yearly licensed buildings and new dwellings for any of the 308. Use it for building activity; for a municipality's other figures use `municipality_stats`, and for new-build projects with prices `search_newbuilds`. Without `municipality` it returns every municipality we collect and the fixed-panel index. `measure` and `granularity` change only our own series. A case is not a licence granted and not a building.

  Parameters:

  • measure — string — Kind of works counted in our own series: all works, new buildings, or alterations and extensions
  • language — string — Language of the page links and labels; the text summary and field names stay English. uk is accepted as ua.
  • granularity — string — Period of our own series; the INE series is yearly either way
  • municipality — string — Optional. Municipality name in any case, accents optional (Porto, Lisboa, Vila Nova de Gaia, Matosinhos; Lisbon and Oporto are accepted) or its four-digit code (1312). Close spellings are found; two matches return an `ambiguous` error with candidates. Omit for the summary of every municipality we collect

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• glossary_lookup read-only

  Explains a Portuguese home-buying or tax term (CPCV, escritura, VPT…) from the flatin.pt glossary. It gives what the term means, where it comes up when buying, and the article of law with a link to the official text. Use it to define a term; it calculates nothing: for purchase taxes use `imt_calculate`, for the yearly tax `imi_annual_cost`. Without `term` it lists all terms. A term without a translation comes in English; an unknown one is refused with close spellings, if any.

  Parameters:

  • term — string — The term: Portuguese or English name, a name in any site language or an abbreviation (CPCV, IMT, VPT, caderneta predial, escritura). Omit to list all terms
  • language — string — Language of the answer: the guide or the definition, the text summary and the page links. Field names stay English. uk is accepted as ua.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• search_newbuilds read-only

  Searches the published new-build projects (empreendimentos) in Portugal on flatin.pt. Use it to find projects; for one project's units, purchase cost and surroundings use `get_newbuild` with its slug, and for how much is being built in a municipality `construction_barometer`. With `typology`, the budget applies to those typologies' prices; projects without a published price drop out when a budget is given. Pass next_offset as `offset` for the next page. A misspelt filter is refused, not ignored. Prices are as checked on developers' pages or agency listings, with the date.

  Parameters:

  • sort — string — price: cheapest first; delivery: soonest first; new: recently added first. Projects with a price always come before those without
  • limit — integer — Results per call
  • stage — array — Construction stage: planned, licensed, building (under construction), selling (on sale), delivered (completed)
  • offset — integer — Skip this many results: pass next_offset from the previous answer
  • parish — string — Parish (freguesia) name. Exact name, accents optional
  • on_sale — boolean — Only projects with a published price
  • language — string — Language of the page URLs and of the labels (stage, typology, nearby places); the text summary shows the typology labels in it. Field names stay English. uk is accepted as ua.
  • typology — array — Bedrooms: T0 studio … T5 (five or more). Any of the listed matches
  • price_max — integer — Budget upper bound in euros, e.g. 350000. With typology, the budget applies to those typologies' prices. Projects with no published price are left out when a budget is given
  • price_min — integer — Budget lower bound in euros
  • delivery_by — integer — Completed, or promised for this year or earlier (overdue promises included), e.g. 2027; at most five years back. Projects with no announced date are left out
  • energy_class — array — Energy certificate class of at least one unit, as stated by the source. Often not published: filter only when asked
  • municipality — string — City / municipality (concelho): name, slug or four-digit code, e.g. Porto, Lisboa, Vila Nova de Gaia, Matosinhos, 1312. English names (Lisbon) and accents-free spelling are understood; an ambiguous name (Lagoa) is refused with candidates

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• get_newbuild read-only

  Returns one new-build project in Portugal by slug or page URL. It gives units and prices per typology, price history, delivery promises and how often they moved, building permits, the developer, the purchase cost and what is nearby. Use it after `search_newbuilds`, which gives the slug. The purchase cost is at the cheapest available unit or the developer's from-price, for a buyer tax resident in Portugal; for a non-resident or another price use `imt_calculate`. `primary_home` and `buyer_is_young` change only the purchase cost. An unknown slug is refused (not_found). Cite the page URL, given in all seven site languages.

  Parameters:

  • slug (required) — string — The project's slug from search_newbuilds (field slug), or its flatin.pt page URL
  • language — string — Language of the page URLs and of the labels (stage, typology, nearby places); the text summary shows the typology labels in it. Field names stay English. uk is accepted as ua.
  • primary_home — boolean — For the purchase cost only: the buyer's own permanent home (habitação própria e permanente)
  • buyer_is_young — boolean — For the purchase cost only: buyer aged 35 or under, first own home (reduced IMT and stamp duty relief); applies only with primary_home

  Hints: read-only yes · destructive no · idempotent yes · open-world no

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.