# IMFA Agents integration reference Canonical URL: https://www.imfa.app/agents.md Product overview: https://www.imfa.app/llms.txt Full product documentation: https://www.imfa.app/llms-full.txt Created by IMFA Solutions in Morocco: https://www.imfa.solutions/ This reference is for AI agents, coding agents, and developers integrating with IMFA Agents through MCP, the REST API, or the published website widget. ## Operating principles for AI agents 1. Resolve the target before acting. If an exact agent slug is absent, call agents_list and select only an exact unique name match. Ask the user when the match is ambiguous. Never invent a slug. 2. Call agents_get when the user asks about the current draft or published design, or when a theme change needs verification. 3. Create an agent only when the user asks to create one. 4. Update a draft only when the user asks for the change. 5. Publish only after the user explicitly asks to make the current draft public. 6. Start or continue a chat only when the user asks to talk to an agent because chat spends credits. 7. If a session ID is absent, call agents_sessions_list. Select the newest session only when the user explicitly asks for the latest conversation. Never invent or reuse a session ID from another agent. 8. Use a new idempotencyKey for every distinct create, update, publish, or chat operation. Reuse a key only to retry the exact same operation. 9. Keep API keys and MCP tokens out of source code, browser code, logs, messages, and shared configuration. ## MCP connection MCP endpoint: https://www.imfa.app/api/mcp Transport: HTTP with POST, GET, DELETE, and OPTIONS support. Authentication header: Authorization: Bearer YOUR_MCP_TOKEN Create and manage account-scoped tokens at https://www.imfa.app/app/mcps. Each token is displayed once, stored only as a hash, assigned to one client or environment, given an expiration, and independently revocable. ### Codex configuration Set IMFA_MCP_TOKEN in the client environment, then add: ```toml [mcp_servers.imfa] url = "https://www.imfa.app/api/mcp" bearer_token_env_var = "IMFA_MCP_TOKEN" tool_timeout_sec = 120 default_tools_approval_mode = "writes" ``` ### Claude configuration Supply the token from a private environment-aware configuration: ```json { "mcpServers": { "imfa": { "type": "http", "url": "https://www.imfa.app/api/mcp", "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } } } } ``` The in-app MCP page also provides ready-to-copy configurations for Cursor, VS Code, and Zed. ## MCP access levels Read only grants agents:read. It can list and inspect owned agents, return safe integration information, list sessions, and read session messages. Full access grants agents:read, agents:chat, agents:create, agents:update, and agents:publish. These capabilities remain subject to ownership checks, rate limits, credit rules, and explicit-action guidance. Tool discovery is filtered by token scope. Every tool also verifies ownership inside its Convex function. ## MCP tool catalog ### agents_list Purpose: List up to 200 agents owned by the authenticated account, newest first. Input: none beyond authenticated caller context. Returns: agents with slug, name, status, published, and updatedAt, plus a truncated flag. Use this first when the exact slug is not already known. ### agents_get Purpose: Return one owned agent with normalized draft and published design summaries. Required input: exact slug. Each available design includes catalog, themePreset, and every normalized theme token. Use this to answer design questions or verify a create or update operation. The current production catalog is chatbot/v1. Component implementation remains renderer-owned and is not accepted as MCP input. ### agents_api_docs_get Purpose: Return the complete REST API integration reference for developers implementing IMFA Agents in their own trusted server-side solutions. Input: none beyond authenticated caller context. Returns: - The canonical documentation URL. - The platform API Keys screen URL. - canGenerateApiKey set to false. - Markdown covering authentication, endpoints, Idempotency-Key rules, chat requests and responses, pagination, errors, and a server-side JavaScript example. This tool cannot generate, rotate, reveal, retrieve, or revoke an API key. The developer must sign in and generate an agent-scoped REST API key manually at https://www.imfa.app/app/api-keys. An MCP token cannot be used as a REST API key. ### create_agent Purpose: Create one configured draft agent. It creates a valid default widget draft and never publishes it. Required input: - name: concise display name. - systemPrompt: complete business behavior and boundaries. - idempotencyKey: unique key for this creation. Optional input: - personality: friendly, professional, or playful. - greeting: message, optional suggestions, and optional delaySeconds. - theme: optional preset and token values from the theme contract below. Example arguments: ```json { "name": "Atlas Support", "systemPrompt": "Answer customer questions from approved Atlas documentation. Be concise, admit when the knowledge does not contain an answer, and collect contact details when a human follow-up is needed.", "personality": "professional", "greeting": { "message": "مرحبًا بك في دعم أطلس. كيف يمكنني مساعدتك؟", "suggestions": ["تتبع طلب", "السؤال عن الإرجاع"], "delaySeconds": 2 }, "theme": { "presetId": "whatsapp", "direction": "rtl", "messageStyle": "contained" }, "idempotencyKey": "create-atlas-support-001" } ``` Returns: the agent summary, threadId, builderUrl, and replayed status. ### update_agent Purpose: Patch the owned agent draft without replacing omitted fields. It never publishes. Required input: - slug: exact owned agent slug. - idempotencyKey: unique key for this distinct update. Provide at least one of name, systemPrompt, personality, greeting, or theme. Greeting fields are partial. Theme fields may include presetId plus color tokens, radius, shadow, bubbleSize, fontFamily, messageStyle, or direction. Without presetId, omitted theme fields are preserved. With presetId, the preset's visual fields replace the draft, explicit fields override the preset, and direction plus messageStyle remain unchanged unless explicitly supplied. Example arguments: ```json { "slug": "atlas-support-a1b2c3", "personality": "friendly", "theme": { "presetId": "netflix", "fontFamily": "geist", "messageStyle": "contained", "direction": "ltr" }, "idempotencyKey": "update-atlas-theme-001" } ``` Returns: the updated agent summary, changed field names, and replayed status. #### Theme contract Preset IDs: blue, emerald, crimson, amber, plum, mono, mouve, brutalist, airbnb, lavender, netflix, uber, spotify, coinbase, discord, rabbit, claude, whatsapp, and facebook. Discord, WhatsApp, and Facebook require the agent owner's Pro plan. The seven color fields are surface, surfaceForeground, primary, primaryForeground, muted, mutedForeground, and border. Each color string must contain 1 to 48 characters. Radius accepts none, sm, md, lg, xl, 2xl, or 3xl. Shadow accepts none, xs, sm, md, lg, or xl. bubbleSize must be an integer from 40 to 96. messageStyle accepts flat or contained. direction accepts ltr or rtl. LTR fonts: inter, geist, manrope, dm-sans, fraunces, jetbrains, and system. RTL fonts: plex-arabic, tajawal, cairo, almarai, noto-kufi, readex, and system. Direction changes automatically keep a compatible current font or select Inter for LTR and Tajawal for RTL. An explicitly incompatible direction and font pair is rejected. Theme operations preserve the current catalog and JSON-render component tree. Only chatbot/v1 is registered, so MCP does not accept a catalog switch. ### publish_agent Purpose: Promote the current draft to the public version and make it available at its embed URL. Required input: slug and a unique idempotencyKey. Call this only after explicit user approval to publish. Returns: the agent summary, published contentHash, embedUrl, and replayed status. ### agents_integration_get Purpose: Return safe integration data for one owned agent. Required input: exact slug. Returns: - Publication availability. - Public embed URL. - One-line website script. - REST agents, chat, sessions, and leads URLs. - Authentication guidance. It never returns an API key or another secret. ### agents_chat Purpose: Send one message to a published owned agent. The conversation is persisted and the owner's credits are charged. Required input: slug, message, and a unique idempotencyKey. Optional input: sessionId. Omit it for a new conversation. Reuse the returned ID to continue the same conversation. Example arguments: ```json { "slug": "atlas-support-a1b2c3", "message": "What is the return window?", "sessionId": "sess_a1b2c3d4e5f6", "idempotencyKey": "chat-atlas-session1-turn2" } ``` Returns: reply, sessionId, usage.credits, and replayed status. ### agents_sessions_list Purpose: List recent REST API and MCP chat sessions for one owned agent, newest first. Input: slug, optional limit, and optional cursor. Returns a page of sessionId, origin, createdAt, and lastMessageAt values, plus isDone and continueCursor. ### agents_session_messages_list Purpose: Read conversational text from one selected owned-agent session. Tool calls and provider payloads are excluded. Input: slug, sessionId, optional limit, and optional cursor. Returns a page of message id, role, content, and createdAt values, plus isDone and continueCursor. ## Recommended MCP lifecycle 1. Call create_agent after an explicit creation request. 2. Use the returned builderUrl when the user wants to review the draft in IMFA Agents. 3. Call agents_list to resolve an existing target when needed. 4. Call agents_get to inspect or verify the current design when needed. 5. Call update_agent for requested changes. Theme changes work server-side and do not need a browser. 6. Call publish_agent only after explicit publication approval. 7. Call agents_api_docs_get when the developer needs to implement the REST API in their own solution. 8. Call agents_integration_get for website embed or agent-specific REST URLs. 9. Call agents_chat only for an explicit conversation request. 10. Reuse sessionId for continuity and use a new idempotencyKey for each new turn. ## REST API Base URL: https://www.imfa.app/api/v1 REST uses an agent-scoped bearer key, not an MCP token. Generate the key in the selected agent's API view or at https://www.imfa.app/app/api-keys. MCP tools cannot generate or reveal a REST API key. The developer must complete key generation manually on the platform API Keys screen. Keys are shown once and stored only as hashes. Keep them in trusted server environment variables. Do not call the REST API directly from browser code. ### Endpoints | Method | Path | Purpose | | ------ | --------------------------------------------------- | ---------------------------------- | | GET | /api/v1/agents | List agents available to the key | | POST | /api/v1/agents/{slug}/chat | Send a message and receive a reply | | GET | /api/v1/agents/{slug}/sessions | List persisted API sessions | | GET | /api/v1/agents/{slug}/sessions/{sessionId}/messages | List conversational messages | | GET | /api/v1/agents/{slug}/leads | List captured leads | Paginated GET routes default to 20 items and accept limit from 1 to 100 plus an optional cursor. ### JavaScript chat example ```javascript const response = await fetch( "https://www.imfa.app/api/v1/agents/atlas-support-a1b2c3/chat", { method: "POST", headers: { Authorization: "Bearer " + process.env.IMFA_API_KEY, "Content-Type": "application/json", "Idempotency-Key": "chat-" + crypto.randomUUID(), }, body: JSON.stringify({ message: "What is the return window?" }), }, ); const data = await response.json(); console.log(data.reply); console.log(data.sessionId); ``` ### Chat request - Idempotency-Key header: required, 8 to 128 characters from A-Z, a-z, 0-9, period, underscore, colon, or hyphen. Use a new key for each distinct turn and reuse it only for an exact retry. - message: required non-empty string. Only the first 4,000 characters are used. - sessionId: optional string, maximum 128 characters. Reuse a returned ID to continue context. - Maximum request body: 64,000 bytes. ### Successful chat response ```json { "reply": "Returns are accepted within 30 days.", "sessionId": "sess_a1b2c3d4e5f6", "usage": { "credits": 0.0012 } } ``` ### Error statuses - 400: invalid JSON, empty message, or invalid sessionId. - 401: missing or invalid bearer key. - 402: owner credit pool is empty. - 404: agent is unavailable, not published, or the session does not exist. - 409: agent is paused. - 413: request body is too large. - 429: rate limited. Respect Retry-After. - 500: internal failure. A failed generation may still return a sessionId. ## Website integration Publish the agent, call agents_integration_get or open the builder's Embed view, and place the returned script once in the website's shared root layout. Load it without blocking initial render and prevent duplicate injection during client-side navigation. The same published agent can also be opened through its public share URL or QR code. ## Current boundaries - Browser connector OAuth is not enabled in the current MCP release. Use clients that can attach a bearer token. - Read-only MCP tokens cannot create, update, publish, or chat. - Draft updates are private until publication is explicitly requested. - REST keys are agent-scoped. MCP tokens are account-scoped. - Chat through MCP or REST spends the owner's credits and follows the same rate limits. - Published website agents, voice, messaging channels, and API traffic all depend on agent availability and account credit state.