Toqan Apps MCP Server

Appearance

Agent Setup ​

Configure your Toqan agent to properly format and display embed content.

Overview ​

When your MCP tool returns a toqanEmbed JSON structure, the agent needs to format it as a YAML block for the frontend to render. This guide shows you how to configure your agent.

Step 1: Add Agent Instructions ​

Add the following instruction to your agent's system prompt or instructions:

When the MCP server returns a embed iframe, build the following structure:

---
embed:
  type: iframe
  src: ${url}
  height: 700
---

Replace ${url} with the actual URL from the toqanEmbed.url field in the tool response.

Step 2: Connect MCP Server ​

Configure your agent to connect to the MCP server:

  • MCP Endpoint: http://localhost:3000/mcp (or your deployed URL)
  • Protocol: HTTP (StreamableHTTPServerTransport)

How It Works ​

Flow Diagram ​

1. User asks agent: "Show me the iFood website"
   ↓
2. Agent calls get_ifood_website tool
   ↓
3. MCP server returns:
   {
     "toqanEmbed": {
       "type": "iframe",
       "url": "https://www.ifood.com.br",
       "height": 700
     }
   }
   ↓
4. Agent formats as YAML block:
   ---
   embed:
     type: iframe
     src: https://www.ifood.com.br
     height: 700
   ---
   ↓
5. Frontend renders iframe in conversation

Example Conversation ​

User:

I want to order some food

Agent:

I'll help you order food. Let me show you the iFood website.

---
embed:
  type: iframe
  src: https://www.ifood.com.br
  height: 700
---

The iFood website will appear embedded in the conversation.

YAML Block Format ​

The YAML block must follow this exact structure:

yaml
---
embed:
  type: iframe
  src: https://example.com
  height: 700
---

Field Details ​

  • type: Must be "iframe" (only supported type)
  • src: The URL to embed (can also use url field)
  • height: Height in pixels (optional, defaults to 400)

Alternative: Using url Field ​

The agent can also use the url field instead of src:

yaml
---
embed:
  type: iframe
  url: https://example.com
  height: 700
---

Both src and url are supported.

Troubleshooting ​

Embed Not Appearing ​

  1. Check YAML syntax - Ensure proper indentation and --- delimiters
  2. Verify URL - Must be HTTPS (required for iframes)
  3. Check CSP - If deployed, ensure domain is in Content Security Policy
  4. Browser console - Look for CSP or iframe errors

Common Errors ​

ErrorCauseSolution
Framing violates CSPDomain not allowedAdd domain to CSP frame-src
Mixed contentHTTP instead of HTTPSUse HTTPS URLs
YAML parse errorInvalid YAML syntaxCheck indentation and format

Advanced: Multiple Embeds ​

You can include multiple embed blocks in a single response:

yaml
Here are two websites:

---
embed:
  type: iframe
  src: https://example.com/1
  height: 400
---

---
embed:
  type: iframe
  src: https://example.com/2
  height: 400
---

Security Considerations ​

  • Sandboxing: Iframes are automatically sandboxed for security
  • CSP: Configure Content Security Policy for production deployments
  • HTTPS: Always use HTTPS URLs for embedded content

Next Steps ​