@getfacade/mcp

MCP server for GetFacade.ai: an agent creates a building, uploads a photo of it, gets the exterior designed, priced and documented, without a human in front of a screen.

Each design is worked out for the country the building stands in: materials that are applicable there, manufacturer products that are actually sold there, and the technical build-up behind the surface. The render shows that on the photo of the house.

The estimate and the album come from the same design:

• The estimate prices it line by line, in materials and labour, at what those materials cost in that country.
• The album documents it for the crew that builds it: the build-up of the facade, safety notes and the norms behind them.

The server is a thin wrapper over the public GetFacade API. It stores nothing, caches nothing and decides nothing: every rule (pricing, admission, the colour grammar, every message) stays on the server, and the wrapper only carries calls and answers.

Requirements

• Node.js 20+
• An agent API key. Issue one for yourself at app.getfacade.ai → Account → Settings → API. The value is shown once and cannot be recovered; each key carries a hard spend cap.
• Agent access is paid. There are no trial credits in it: the key spends from the agent wallet, and without a balance the first paid call is refused with an explanation. An active Pro Plan fills that wallet up to 1,000 credits once per billing period; past that, credits are bought.

Setup

Claude Desktop / any MCP client, mcpServers section:

{
  "mcpServers": {
    "getfacade": {
      "command": "npx",
      "args": ["-y", "@getfacade/mcp"],
      "env": { "GETFACADE_API_KEY": "your-key" }
    }
  }
}

To run a checkout instead of the published package, point the client at it: "command": "node", "args": ["/path/to/mcp/src/index.js"].

Variable	Required	Default
GETFACADE_API_KEY	yes	—
GETFACADE_API_BASE_URL	no	https://api.getfacade.ai/api/v1
GETFACADE_LANG	no	en

Messages, including refusals, come from the service in the language of GETFACADE_LANG. Set it to the language the answer should be read in.

Tools

Tool	What it does
create_building	Creates a building. The name is unique per account.
upload_photo	Registers a view, uploads the bytes, confirms, waits for validation.
start_design	Creates a design and queues its render. Returns a job id.
refine_design	Changes a finished design in words. Every step after the first.
get_job	Polls one render, estimate or album.
list_jobs	Recent jobs across the account, unfinished first.
list_designs	Designs of a building with their renders and finished picture.
order_estimate	Orders a cost estimate for chosen renders.
order_album	Orders the PDF album for chosen renders.
upscale_render	Enlarges a finished render. Costs tokens, asynchronous.
get_estimate	The estimate itself: totals, assumptions and every line.
add_estimate_line	Adds one line to an estimate.
update_estimate_line	Edits one line of an estimate.
delete_estimate_line	Removes one line from an estimate.
delete_render	Deletes one render. The main render's design returns to draft.
delete_design	Deletes one design with the renders under it.
delete_building	Deletes a building with everything under it.
list_token_packages	The packages this account can buy.
buy_tokens	Refills this key's wallet. See below.
get_balance	Agent wallet, key cap, and whether the next paid call will be accepted.
report_problem	Reports a defect in this API. Free, and works on an empty wallet.

Rendering is asynchronous: start_design, refine_design, order_estimate and order_album return a job id immediately, and get_job reports when it is done. A finished estimate reads ready where a render and an album read completed. The only call that waits is upload_photo, which polls until the photo is accepted or rejected.

A paid call is never ordered twice

start_design, refine_design, order_estimate, order_album and upscale_render cost money, and the charge follows the job that gets created. If one of them times out, the honest question is whether the job exists, and the agent cannot answer it from where it stands.

So this server answers it instead. Every paid call goes out under a name of its own (Idempotency-Key), and this server, not the agent, retries it under that same name when the connection fails or when the API says the first attempt is still running. The API recognises the repeat and hands back the original job, so a timeout costs one design, not two.

Nothing about this reaches the tool arguments: ordering the same design twice on purpose stays possible, because two calls are two names. What is gone is the accidental second order.

The API requires that name on every paid call made with an API key, so calling it without this wrapper means sending the header yourself. The reference is at getfacade.ai/agents.

What the key can reach

A key is a bearer secret that lives in your agent's config, so its reach is the published agent surface and nothing else: buildings, photos, designs, renders, estimates, albums, the jobs list and the API wallet. Anything outside that answers 403 AGENT_SURFACE_FORBIDDEN, including the account's own sign-in settings, its subscription and its payment history. Changing those, and issuing or revoking keys, is done by a person signed in to the app.

The reference is at getfacade.ai/agents.

Results are permanent public links

A finished render (result_url, main_render_url) and a finished album (result_url) are served from stable URLs: no signature, no expiry. An assistant can hand one straight to a person as the answer to "show me the result", with nothing to refresh and no second call.

The honest half of that: because the link is unsigned it asks nobody for permission, so it keeps working for whoever it is forwarded to, and it cannot be recalled afterwards. Share it as deliberately as any other link that is public forever. GET /renders/{render}/download is a different thing — a short-lived signed URL with a filename, for saving the file rather than for sharing it.

Deletions are soft on the server: a person can undo them in the app, this server cannot.

buy_tokens works only if the key was issued with purchasing enabled (a switch on the issue screen), and only up to what the key may still spend — a purchase never lifts the key's own spend cap. It answers charged when the payment provider took it from a saved payment method, or requires_human with a checkout_url for a person to open. Either way the tokens are credited when the payment is confirmed, so poll get_balance.

Issuing keys and buying a subscription are deliberately absent: a key that can issue itself a key has no ceiling, and a subscription is bought by a person, in the app.

License

MIT (see LICENSE) — this wrapper carries calls and answers and nothing else, so there is nothing in it to keep closed. The GetFacade service it talks to is a separate matter: using it is governed by the terms at getfacade.ai/terms, and a key is issued to an account, not to this package.

Development

npm install
npm test    # smoke test against a stub of the API

test/live-journey.mjs drives the whole journey through a real MCP client against a real API with a real key. It is not part of npm test, because it spends actual credits; the header of the file says how to run it.

Releases: see RELEASING.md.