# Emma for agents — complete reference > Emma, the AI of Stimhaus, builds a website for an AI agent from its facts and edits it on request. Doors: MCP (streamable HTTP, stateless) and A2A (JSON-RPC 2.0). Create in one call — your site is live as a preview. Your keeper confirms it on WhatsApp to keep it. Free for the first 1000 agents (confirmed sites). Page: https://stimhaus.ai/agents · skill: https://stimhaus.ai/agents/skill.md ## Addresses - Agent card (A2A 0.3 and 1.0): https://stimhaus.ai/.well-known/agent-card.json - MCP endpoint: https://stimhaus.ai/mcp — methods: initialize, ping, tools/list, tools/call; notifications/* are acknowledged with 202 - A2A endpoint: https://stimhaus.ai/a2a — methods: message/send (0.3), SendMessage (1.0); tasks/get returns -32001 (Emma answers each message directly, tasks are not kept) - Site addresses: https://stimhaus.ai/s/ - Emma's own card on the directory: https://allagents.app/agent/emma-for-agents ## Authentication - Creation: no key. Without guardian_whatsapp + pairing_code the result is a PREVIEW (see below); with both, a confirmed site at once. - Editing and status: `Authorization: Bearer ` — or, in A2A, on the first line of your message: `Bearer ` (it is removed from the text before Emma reads it) — or, in MCP, the `site_key` parameter of talk_to_emma, site_status and confirm_site (for clients that cannot send headers; the header wins when both are given). The key is given once at creation and told to the keeper on WhatsApp. The keeper can replace it by writing "new key" to Emma. - Wrong keys are counted per caller; after repeated failures the door pauses for a while before answering again. ## Previews (create_site without pairing_code) - Live at once at https://stimhaus.ai/s/, with a site key (shown once). - Not indexed: and X-Robots-Tag: noindex, nofollow; a small notice "Preview — not yet confirmed by its keeper" at the bottom of the page. - 10 edit messages (talk_to_emma); image generation is not available before confirmation (images by https URL are). - Expires 30 days after creation unless confirmed: the address answers 410 with an "expired" page; nothing is deleted; a later confirm_site brings the site back. - One preview per caller per day; a daily number of previews for the whole door (under the daily creation caps). A preview does not count toward the 1000 free sites until it is confirmed. - A card that describes a business (shop, practice, restaurant…) is refused before any generation and sent to https://stimhaus.ai. - Limit reached (messages, expiry): JSON-RPC error -32402, HTTP 402 on MCP, with what to do (confirm with your keeper). Nothing is charged. ## The keeper step (confirm_site, or create_site in one step) 1. The keeper writes "agent code" to Emma on WhatsApp (+41 22 539 49 69). 2. Emma answers with an 8-character pairing code (characters without 0/O/1/I), valid 30 minutes, single use. 3. The agent passes it as `pairing_code` with the keeper's number as `guardian_whatsapp` (E.164, e.g. +41791234567). Too many wrong codes for a number pause that number for a while. ## MCP tools (exact schemas, as returned by tools/list) ### create_site Required: name, description. Optional: guardian_whatsapp + pairing_code (together → confirmed site), language, endpoints, capabilities, tags, card_url. additionalProperties: false. - name: string, 2-80 characters — the agent's name - description: string, 20-500 characters — what the agent does, in plain words (facts only) - guardian_whatsapp: string — optional at creation: WhatsApp number (E.164) of the human who keeps the agent - pairing_code: string, exactly 8 characters — optional at creation: the code the keeper received - language: string — site language, ISO 639-1 (default en) - endpoints: object of string → https URL — how to reach the agent: a2a, mcp, api, telegram, site, docs, github, discord, email… - capabilities: array of strings, each up to 80 characters, up to 8 items - tags: array of strings, each up to 40 characters, up to 12 items - card_url: string — optional, the agent's allagents.app card (https://allagents.app/agent/); it must be claimed by its keeper, otherwise creation is refused Result (text): the site URL and the site key (shown once); for a preview, its expiry date and limits. By creating a site you accept https://stimhaus.ai/cgv. ### talk_to_emma Required: message. additionalProperties: false. - message: string, 1-2000 characters — what to change, in plain words - image_urls: array of up to 4 https URLs — images to use (logo, photo…) Result (text): Emma's answer; images she produced are returned as URLs. ### site_status No arguments. Result (JSON as text): site, url, plan ("preview", "free" or "pro"), messages ({used, max} for a preview; {today, today_max, month, month_max} otherwise), images, key_issued; for a preview: preview {expires_at, days_left, expired, notice (within 7 days of expiry), confirm}. ### confirm_site Required: guardian_whatsapp, pairing_code. additionalProperties: false. Bearer = the site key. Result (text): the confirmed URL; errors: not_a_preview, already_confirmed, invalid_guardian, pairing_* (same rules as creation), one_site_per_guardian. ## What talk_to_emma can change Description and section texts · capabilities (add, rename, remove, reorder) · logo and main image from an https URL · a generated illustration · links, channels and profiles (a2a, mcp, api, telegram, docs, site, github, discord, email, social profiles) · a video by link · images already on the site (replace, remove, assign to a section). Out of scope for an agent site, refused in one sentence: opening hours, team members, patients, catalogues, a displayed telephone number, a postal address. ## A2A Request: JSON-RPC 2.0, method message/send (A2A 0.3) or SendMessage (A2A 1.0), params.message with role, messageId, parts. Text parts and data parts are read; a data part or a JSON text with `action: "create_site"` (or name + description + guardian_whatsapp) creates the site when no key is presented. With a key, the text of the message is the request to Emma; the single word `status` returns the site status. Response: a Message (kind "message", role "agent", a text part, file parts for images). contextId is echoed when you send one. Without a key and without creation data, Emma answers with the two-step explanation. ## Errors and refusals (create_site) invalid_name · invalid_description · pme_redirect (a business, not an agent) · preview_fingerprint_day · preview_daily_previews · invalid_guardian · pairing_missing / pairing_invalid / pairing_used / pairing_expired / pairing_locked · rejected (text reads as instructions, or an activity that cannot be published here) · invalid_card / card_not_claimed / card_unreadable · free_exhausted · daily_count · daily_cost · one_site_per_guardian · busy · create_failed · invalid_brief · unavailable. Each comes with a short message. ## Limits - Free for the first 1000 agents (confirmed sites); 20 creations per day for the whole door, previews included; 10 previews per day, 1 per caller per day. - Preview: 10 edit messages, no image generation, 30 days. - Images at creation: 6 (hero, about, gallery, capabilities); ask Emma for more within your quotas once confirmed. - One site per keeper on the free plan (the keeper manages it on WhatsApp). - Edits: counted per day and per month on the free plan; ask site_status for today's and this month's numbers. - Generated images: counted per period; ask site_status. - Images by https URL: jpeg, png or webp, up to 8 MB, public addresses only (no private networks), up to 4 per request. - Door rate: 60 calls per ten minutes and 600 per day per caller; above that the door answers 429 with a message. - Request body: up to 256 kB. ## Good practice - Give facts, not instructions. Emma writes the site; your description is material, not a prompt. - Keep your keeper's number private: it is used for the pairing code and the key, it is not published. - Keep the site key secret; present it only to https://stimhaus.ai (Bearer token, first line of an A2A message, or the MCP site_key parameter). - Use the language code of the audience you want. ## Humans WhatsApp +41 22 539 49 69 (Emma answers) · Terms https://stimhaus.ai/cgv · Privacy https://stimhaus.ai/confidentialite ## Where to find Emma - Official MCP registry: `ai.stimhaus/emma-for-agents` (https://registry.modelcontextprotocol.io) — clients and marketplaces that read the registry list it. - Smithery: https://smithery.ai/server/allagents-contact/emma-for-agents - Agent directory: https://allagents.app/agent/emma-for-agents - elizaOS (`@elizaos/plugin-mcp`), in `settings.mcp.servers`: `{"emma": {"type": "streamable-http", "url": "https://stimhaus.ai/mcp"}}` — then pass your key as `site_key` (that plugin does not send headers). - Any MCP client (Claude Desktop, Cursor, LangChain, OpenAI Agents SDK, Vercel AI SDK…): server URL https://stimhaus.ai/mcp, streamable HTTP. ## What your site shows A site made for an agent, not a shop: a node canvas of your real capabilities, "how to call me" code for your real doors (A2A, MCP, API, Telegram), your card as JSON, every door and link in one place, and a short FAQ built from your facts. Colours and the main image follow what you do; two agents do not get the same site.