# PDMFácil agent guide — Portuguese land-use planning

Use PDMFácil to consult Plano Diretor Municipal (PDM), zoning classification, available building parameters, RAN and REN at a point in Portugal. It is an informational service using municipal and national sources, not a municipal approval or a cadastral certificate.

Discovery: https://pdmfacil.pt/developers
OpenAPI: https://pdmfacil.pt/openapi.json
REST: POST https://pdmfacil.pt/api/v1/agent
MCP: https://pdmfacil.pt/mcp (Streamable HTTP, stateless JSON)
Coverage: https://pdmfacil.pt/concelhos

## Connect and pay

1. The account owner registers/signs in at https://pdmfacil.pt/developers, buys prepaid credits using the existing Stripe checkout, and creates an API key with a lifetime credit limit. Keys expire after one year and can be revoked. The raw key is shown once.
2. Store the key in the client secret store or environment variable PDMFACIL_API_KEY. Send Authorization: Bearer <key>. Never put keys in URLs, prompts, shared logs or screenshots.
3. MCP clients can use OAuth authorization-code + S256 PKCE with dynamic public-client registration, or a configured Authorization header. OAuth opens a PDMFácil consent page where the owner chooses a credit limit. Grants last 30 days and can be revoked from /developers; authorize again to renew (no refresh tokens). Tokens are bound to https://pdmfacil.pt/mcp and cannot be used on REST. Server-backed and desktop clients are supported; direct cross-origin browser MCP connections are not supported. No SDK install is required for REST.
4. A successful PDM classification costs one credit. The key also has an independent lifetime spending ceiling. No automatic top-up. A 402 provides a human billing URL; it is NOT an x402/MPP payment challenge. Never ask a user to send card details to the model.

Packages (EUR, shared with the website):
- Inicial: 5 credits for EUR 4.99
- Profissional: 35 credits for EUR 24.99
- Premium: 180 credits for EUR 99.99

## Workflow

- Call coverage (free, no key needed) to list integrated municipalities. Coverage is not a promise that every point has legal classification.
- If coordinates are unknown, call search_locations with a precise address and municipality. Call resolve_location for a candidate with needsResolution, using its display and magicKey when provided (BNM candidates can omit magicKey). Both are free but require a key.
- Ask the user to select/confirm the intended point when candidates are ambiguous. Street and municipality centres are not parcel coordinates. Do not guess a parcel or buy multiple results to resolve ambiguity.
- Call query_pdm with confirmed decimal WGS84 lat, lng and a new idempotency_key (8–128 letters/digits/._:-). Longitude is usually negative in Portugal. Never reverse latitude and longitude.
- Retry network failures with the SAME idempotency_key and identical coordinates. The saved response is returned with replayed=true, without another charge. Different coordinates under the same key produce 409. Balances in replays are historical; billing returns the current balance.
- Missing classifications, unavailable sources and COS land-cover-only estimates cost zero credits and are not saved as completed requests. Retrying these may return newer data.
- Cite citation_url and official sources. Preserve dataWarnings, errors, confidence, source dates and nationalConstraints.failedSources. An empty or unchecked constraint result is not proof that no restriction exists. A point result is not a whole-parcel assessment.
- billing returns prices, remaining credits, key budget and the checkout handoff URL. Keys cannot buy credits or access card/profile details.

## REST example

curl https://pdmfacil.pt/api/v1/agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PDMFACIL_API_KEY" \
  -d '{"operation":"query_pdm","arguments":{"lat":39.744,"lng":-8.807,"idempotency_key":"your-unique-request-001"}}'

Use a new identifier for a deliberate new purchase; preserve the old one for retries. The example coordinates identify a point in Leiria, not the user's land.

## MCP

Send Accept: application/json, text/event-stream and Content-Type: application/json.
Anonymous initialization returns 401 with WWW-Authenticate pointing to /.well-known/oauth-protected-resource/mcp. Authorization-server metadata is at /.well-known/oauth-authorization-server.
Initialize with protocolVersion 2025-11-25, 2025-06-18 or 2025-03-26; use the negotiated MCP-Protocol-Version on subsequent requests. No session ID is required. GET returns 405 because this server does not provide an unsolicited event stream.
Tools: coverage, search_locations, resolve_location, billing, query_pdm.
Tool failures have isError=true and a machine-readable error.code. HTTP errors include 401, 402, 409, 429 and 503 on REST. Rate limit is 100 requests/minute per process per key and per source IP; honor Retry-After when present. Polling rapidly will not speed up GIS providers.

Examples of user intent: “Check the PDM at these coordinates in Portugal”; “Does this point intersect RAN or REN?”; “What building parameters are available for this location?” Never promise permission to build.