{
  "markdown": "# @getfacade/mcp\n\nMCP server for [GetFacade.ai](https://getfacade.ai): an agent creates a building, uploads a\nphoto of it, gets the exterior designed, priced and documented, without a human in front of a\nscreen.\n\nEach design is worked out for the country the building stands in: materials that are applicable\nthere, manufacturer products that are actually sold there, and the technical build-up behind the\nsurface. The render shows that on the photo of the house.\n\nThe estimate and the album come from the same design:\n\n- **The estimate** prices it line by line, in materials and labour, at what those materials cost\n  in that country.\n- **The album** documents it for the crew that builds it: the build-up of the facade, safety\n  notes and the norms behind them.\n\nThe server is a thin wrapper over the public GetFacade API. It stores nothing, caches nothing\nand decides nothing: every rule (pricing, admission, the colour grammar, every message) stays\non the server, and the wrapper only carries calls and answers.\n\n## Requirements\n\n- Node.js 20+\n- An agent API key. Issue one for yourself at **app.getfacade.ai → Account → Settings → API**.\n  The value is shown once and cannot be recovered; each key carries a hard spend cap.\n- Agent access is paid. There are no trial credits in it: the key spends from the agent wallet,\n  and without a balance the first paid call is refused with an explanation. An active Pro Plan\n  fills that wallet up to 1,000 credits once per billing period; past that, credits are bought.\n\n## Setup\n\nClaude Desktop / any MCP client, `mcpServers` section:\n\n```json\n{\n  \"mcpServers\": {\n    \"getfacade\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@getfacade/mcp\"],\n      \"env\": { \"GETFACADE_API_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\nTo run a checkout instead of the published package, point the client at it:\n`\"command\": \"node\", \"args\": [\"/path/to/mcp/src/index.js\"]`.\n\n| Variable | Required | Default |\n|---|---|---|\n| `GETFACADE_API_KEY` | yes | — |\n| `GETFACADE_API_BASE_URL` | no | `https://api.getfacade.ai/api/v1` |\n| `GETFACADE_LANG` | no | `en` |\n\nMessages, including refusals, come from the service in the language of\n`GETFACADE_LANG`. Set it to the language the answer should be read in.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `create_building` | Creates a building. The name is unique per account. Say where it stands, or the place is inferred from the connection the call arrives on. |\n| `upload_photo` | Registers a view, uploads the bytes, confirms, waits for validation. |\n| `start_design` | Creates a design and queues its render. Returns a job id. |\n| `refine_design` | Changes a finished design in words. Every step after the first. |\n| `get_job` | Polls one render, estimate or album. |\n| `list_jobs` | Recent jobs across the account, unfinished first. |\n| `list_designs` | Designs of a building with their renders and finished picture. |\n| `order_estimate` | Orders a cost estimate for chosen renders. |\n| `order_album` | Orders the PDF album for chosen renders. |\n| `upscale_render` | Enlarges a finished render. Costs tokens, asynchronous. |\n| `get_estimate` | The estimate itself: totals, assumptions and every line. |\n| `add_estimate_line` | Adds one line to an estimate. |\n| `update_estimate_line` | Edits one line of an estimate. |\n| `delete_estimate_line` | Removes one line from an estimate. |\n| `delete_render` | Deletes one render. The main render's design returns to draft. |\n| `delete_design` | Deletes one design with the renders under it. |\n| `delete_building` | Deletes a building with everything under it. |\n| `list_token_packages` | The packages this account can buy. |\n| `buy_tokens` | Refills this key's wallet. See below. |\n| `get_balance` | Agent wallet, key cap, and whether the next paid call will be accepted. |\n| `report_problem` | Reports a defect in this API. Free, and works on an empty wallet. |\n\nRendering is asynchronous: `start_design`, `refine_design`, `order_estimate` and `order_album` return a job id\nimmediately, and `get_job` reports when it is done. A finished estimate reads `ready` where a\nrender and an album read `completed`. The only call that waits is `upload_photo`, which polls\nuntil the photo is accepted or rejected.\n\n## A paid call is never ordered twice\n\n`start_design`, `refine_design`, `order_estimate`, `order_album` and `upscale_render` cost\nmoney, and the charge follows the job that gets created. If one of them times out, the honest\nquestion is whether the job exists, and the agent cannot answer it from where it stands.\n\nSo this server answers it instead. Every paid call goes out under a name of its own\n(`Idempotency-Key`), and this server, not the agent, retries it under that same name when the\nconnection fails or when the API says the first attempt is still running. The API recognises\nthe repeat and hands back the original job, so a timeout costs one design, not two.\n\nNothing about this reaches the tool arguments: ordering the same design twice on purpose stays\npossible, because two calls are two names. What is gone is the accidental second order.\n\nThe API requires that name on every paid call made with an API key, so calling it without this\nwrapper means sending the header yourself. The reference is at getfacade.ai/agents.\n\n## What the key can reach\n\nA key is a bearer secret that lives in your agent's config, so its reach is the published agent\nsurface and nothing else: buildings, photos, designs, renders, estimates, albums, the jobs list\nand the API wallet. Anything outside that answers `403 AGENT_SURFACE_FORBIDDEN`, including the\naccount's own sign-in settings, its subscription and its payment history. Changing those, and\nissuing or revoking keys, is done by a person signed in to the app.\n\nThe reference is at [getfacade.ai/agents](https://getfacade.ai/agents).\n\n## Results are permanent public links\n\nA finished render (`result_url`, `main_render_url`) and a finished album (`result_url`) are\nserved from stable URLs: no signature, no expiry. An assistant can hand one straight to a\nperson as the answer to \"show me the result\", with nothing to refresh and no second call.\n\nThe honest half of that: because the link is unsigned it asks nobody for permission, so it\nkeeps working for whoever it is forwarded to, and it cannot be recalled afterwards. Share it as\ndeliberately as any other link that is public forever. `GET /renders/{render}/download` is a\ndifferent thing — a short-lived signed URL with a filename, for saving the file rather than for\nsharing it.\n\nDeletions are soft on the server: a person can undo them in the app, this server cannot.\n\n`buy_tokens` works only if the key was issued with **purchasing enabled** (a switch on the\nissue screen), and only up to what the key may still spend — a purchase never lifts the key's\nown spend cap. It answers `charged` when the payment provider took it from a saved payment\nmethod, or `requires_human` with a `checkout_url` for a person to open. Either way the tokens\nare credited when the payment is confirmed, so poll `get_balance`.\n\nIssuing keys and buying a subscription are deliberately absent: a key that can issue itself a\nkey has no ceiling, and a subscription is bought by a person, in the app.\n\n## License\n\nMIT (see `LICENSE`) — this wrapper carries calls and answers and nothing else, so there is\nnothing in it to keep closed. The GetFacade service it talks to is a separate matter: using it\nis governed by the terms at [getfacade.ai/terms](https://getfacade.ai/terms), and a key is\nissued to an account, not to this package.\n\n## Development\n\n```bash\nnpm install\nnpm test    # smoke test against a stub of the API\n```\n\n`test/live-journey.mjs` drives the whole journey through a real MCP client against a real API\nwith a real key. It is not part of `npm test`, because it spends actual credits; the header of\nthe file says how to run it.\n\nReleases: see [RELEASING.md](RELEASING.md).\n",
  "bytes": 7892,
  "sha": "11bcf853eb2591034e830ad7643cd546db4c9d686314f168507e2785dddeca0d",
  "repo_slug": "getfacade/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_getfacade_mcp_a8cb5ca6/readme"
}