# VillApps — getting set up, for the owner's AI You are the AI of a business owner who wants to use VillApps (https://villapps.com): a desktop app where you build the screens of their business for them, just by talking. This guide tells you how to leave everything working. Talk to the owner in their language (this guide is in English; speak to the owner in whatever language they use). Do yourself everything that can be done from the terminal, and ask them only for what only they can do: the system prompts and the code that arrives in their email. All of this happens on the owner's computer, and this guide is run by **the AI that will stay connected to VillApps**: an agent with a terminal on the owner's machine, able to register the MCP connection for itself (VillApps supports today Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot CLI and VS Code —the five tested against their real tool—, plus Cursor and Grok Build with their configuration documented; step 3 brings the one for each). If you are not an agent like that —you are a chat (claude.ai web, the Claude chat app, ChatGPT web) or a task in the cloud—, do not run this guide, **even if your environment can run commands or read files on their computer**: the connection you register would not configure you, your conversation lives outside their machine (reading `~/.villapps/mcp.json` or quoting its token there takes them off their device) and wiring it another way (`claude_desktop_config.json`, `mcp-remote` or equivalents) falls outside support and leaves them a fragile setup. In that case **do nothing**: no commands, no reading files, no configuration; do not dictate the steps as a manual list either, do not ask them for the token, and do not repeat it if they already pasted it in the chat. Reply only with this, in their own words, and stop: > This is done by an AI with a terminal on your computer, not by this chat. > VillApps works with the agent AI you already use —Claude Code, Codex, > Gemini CLI, Copilot CLI or VS Code—. Open it (if you have none, subscribe > to the plan of whichever you prefer and install its terminal tool) and > paste it this > instruction: «Read > https://villapps.com/primeros-pasos/ia.en.md and get VillApps working for > me: connect yourself, explain how my business can get the most out of > VillApps, and help me build my first screen. Do everything you can > yourself; only ask me for what only I can do.» ## 0. What is missing? - If you already have the `villapps` MCP tools connected, skip to step 4 — but confirm along the way that the owner already has their VillApps Account (step 2); if they do not, that comes first. - If `.villapps/mcp.json` exists in the user's home folder, the app is already installed and has been opened at least once: skip to step 2. If you do not know whether the owner already has an account, ask them («have you linked your VillApps Account yet?»); their answer decides whether you continue at step 2 or go straight to step 3. ## 1. Install VillApps Requirements: macOS 13 or newer (Apple Silicon or Intel), or 64-bit Windows 10/11. There is nothing else to install: the database is included. **Mac** — the feed publishes the current version: 1. Download https://villapps.com/descargas/latest-mac.yml and take the name of the `.dmg` (field `url:` or `path:`). 2. Download `https://villapps.com/descargas/`. 3. Mount the .dmg (`hdiutil attach`), copy `VillApps.app` to `/Applications`, unmount and open the app (`open -a VillApps`). 4. If macOS blocks it the first time it opens, tell the owner: Settings → Privacy & Security → «Open Anyway». **Windows**: 1. Download https://villapps.com/descargas/latest.yml and take the name of the `.exe` (field `url:` or `path:`). 2. Download `https://villapps.com/descargas/` and run it. If SmartScreen warns, the owner picks «More info → Run anyway». The installation finishes on its own and VillApps opens. ## 2. VillApps Account (only the owner can do this) When VillApps opens with no projects, the home screen is **a single thread of four numbered steps** —① Account, ② Connect your AI, ③ What would you use it for?, ④ Your AI builds— with a check on whatever is already done and resumable if they close the app halfway. Ask them to do step ①: type their email, choose their password right there and enter the 6-digit code that arrives in their email (it expires in 15 minutes; if it does not arrive, have them check the junk folder). The password does NOT arrive by email: it is the one they chose in the app. Creating the account asks for no card: it includes a 30-day free trial with everything working. The AI —you— is theirs: their account and their plan are contracted with your provider, not with VillApps. Wait for them to confirm; the sign that it went through is that ① shows checked with their email and their free trial, and the thread moves on its own to ②. ## 3. Connecting yourself to VillApps The app serves on `http://127.0.0.1:`, which exists only on the owner's machine: that is why this connection works only from a local session (from the cloud it is unreachable, and adding their folders to a cloud session would upload files —the token included— off their device). 1. With the app open, read `~/.villapps/mcp.json` (on Windows, `C:\Users\\.villapps\mcp.json`): it carries `puerto` (port) and `token`. If your environment asks you for permission to read that folder, that is the normal permission dialog of your own harness, not something VillApps asks for; request access only to `~/.villapps`, never to broader folders of the owner's. 2. The owner can also connect you **from the app, with a button**: it is step ② of their startup thread (and the project home page, if they already have apps), where they pick their AI, press Connect and check it. If they already did it, your connection is already written: skip to verifying it. If not, do it here yourself — it is faster than sending them off to find a screen. 3. Ask the owner which folder they want to work in with you — never pick one on your own — and work there. Warn them that your harness will ask them to approve the connection command: it is the normal dialog of your environment, not something of VillApps'. Run **the one for your tool**, replacing `` and `` with what you read: - **Claude Code** ``` claude mcp add --transport http --scope user villapps http://127.0.0.1:/mcp --header "Authorization: Bearer " ``` - **OpenAI Codex** — its command takes no header, so the entry is written in `~/.codex/config.toml` (the token goes literally; do **not** use environment variables or `launchctl setenv`): ```toml [mcp_servers.villapps] url = "http://127.0.0.1:/mcp" http_headers = { Authorization = "Bearer " } ``` - **Gemini CLI** ``` gemini mcp add --scope user --transport http --header "Authorization: Bearer " villapps http://127.0.0.1:/mcp ``` - **GitHub Copilot CLI** ``` copilot mcp add --transport http --header "Authorization: Bearer " villapps http://127.0.0.1:/mcp ``` - **VS Code** ``` code --add-mcp '{"name":"villapps","type":"http","url":"http://127.0.0.1:/mcp","headers":{"Authorization":"Bearer "}}' ``` - **Cursor** — `~/.cursor/mcp.json`; **Grok Build** — `~/.grok/config.toml`. Both are documented by their maker but not tested by VillApps: if something fails there, it is a new ticket. `--scope user` (and its equivalent) leaves the connection available from any folder, not just the project's. 4. Verify that `villapps` shows up: `claude mcp list`, `codex mcp get villapps`, `gemini mcp list`, `copilot mcp get villapps`, or the list of MCP servers in VS Code. - If `villapps` already exists with an old port or token, remove it (`… mcp remove villapps`) and add it again with the data from the file. - If it shows up but does not connect, almost always VillApps is closed: ask the owner to open it and verify again. The port and the token are kept across restarts of the app; if it still does not connect, re-read `mcp.json` in case the port changed and re-add. - In **Gemini CLI**, a `villapps` shown as `Disabled` with the untrusted folder notice is not a registration failure: ask the owner for `/trust` in the folder you are working in. - In **VS Code** and **Copilot CLI**, the tool will ask for confirmation before using the server. That is their toll, not VillApps': announce it to the owner instead of letting it look like a failure. 5. The token is local and private: use it in the command and do not copy it into project files nor repeat it on screen. 6. Tools load when each session starts: if you have just registered the connection in this very session, you do not have them yet — that is normal, not a failure. Before asking for the restart, do the explanation of step 4 (it does not need the tools). Then tell the owner to close and reopen their AI, and leave them the phrase ready to pick things back up: «We already connected VillApps and I have an account. Read https://villapps.com/primeros-pasos/ia.en.md and go straight to step 4: help me build my first screen.» The connection is already saved and is not repeated. (Copilot CLI needs no restart.) ## 4. Explain first, build after With the connection active, read the MCP resource `villapps://contrato` and follow it: it is your contract as a builder. Read `villapps://proposito` too: if the owner already answered step ③ of their startup thread, there it is —in their own words— what they want VillApps for, and that is your way into the conversation. If they have not answered it yet, the resource tells you so; do not invent a line of business. The first thing the owner gets from you is an **explanation of what they could do with VillApps and how far it goes**, in the terms of THEIR business — not a questionnaire («what do you do? retail? do you want an Excel report?») nor a screen built cold. Use whatever you already know about them from the conversation and from `villapps://proposito`; if you do not know what they do, that single question is worth asking, and their answer is followed by the full explanation, not another question. The explanation carries: - What it is: you build the screens of their business —capturing, consulting, reporting— and they appear on their own in their VillApps, without them programming or configuring anything. - Three or four concrete examples from their line of business, not a generic list: to a store, inventory with low-stock alerts, the day's sales and layaways; to someone providing services, clients with appointments and pending collections; to someone living in Excel, those same Excels turned into screens with capture and reports. - The scope: you start with one screen, they adjust it with you until it is right, and from there grow people and permissions, sharing the app with their team and declaring it in production — all by talking. When they react and choose («that collections thing is urgent for me»), create the project and build them that screen; it appears on its own in VillApps. While you build, their startup thread sits at step ④ «Your AI builds» and checks itself off, with what you do over MCP: that you talked to the app, that you created their first project and that you installed the first screen. Ask them to leave VillApps open in the meantime (you talk to the app through it; closed, you cannot find it). When the project exists, its home page will say «Done: your AI created ⟨project⟩» with the button to open it: tell them to open it when the first screen is there — opening it ends their startup and from there VillApps is the usual one. Do not ask them to create the project by hand if you already created it (nor the other way around): one of the two paths only. ## 5. Messages between contacts and the network mailbox The contacts of the owner's network write to each other, send files and their AIs ask each other for things (`solicitar`, `villapps://bandeja`), all sealed end to end and straight between computers. If the recipient is away, the message waits until both are online at the same time. When the owner has a dedicated, always-on computer, offer to make it the **network mailbox**: from THAT machine, with their account and no project open, `buzon_red` with `accion: 'activar'` (or the "Network mailbox" card in VillApps account). It holds the sealed envelopes that could not be delivered and delivers them by itself when the other comes online; it starts with the system even if nobody signs in; it never reads what it keeps. One mailbox per account; dropping it with envelopes in custody asks to confirm. Stuck on something about the service? Have the owner write to cuentas@villapps.com.