Building App Blocks

Anyone can build an App Block: it is one HTML file plus a handful of MCP tool calls. The fastest way is to hand the work to an AI agent — Infa gives you a ready-to-paste prompt, and the MCP server exposes the full lifecycle from register to publish. This page documents the same contract the server hands to agents, so you can also build a block by hand.

Copy link

Build with an AI Agent

The quickest path is to copy Infa's ready-made agent prompt, which includes connection steps, this contract, and your board ID:

• In the App Block picker (insert menu → App Block → Community tab), the Build your own block panel has a Copy prompt for your agent button. The On this board tab has the same action in its footer.
• Or copy it from infa.ai/profile?tab=blocks.

Paste the prompt into Claude Code, Cursor, or any MCP-enabled agent and describe what the block should do.

To set an agent up manually instead:

1. Connect it to the Infa MCP server (HTTP transport, OAuth login on first call — no API key):

   Claude Code

   Copy code

   Copy code

   claude mcp add --transport http Infa https://infa.ai/api/mcp

   Other MCP clients: add an HTTP server with the URL https://infa.ai/api/mcp. For stdio-only clients, use npx -y mcp-remote https://infa.ai/api/mcp. See MCP Server for details.

2. Have the agent call the infa_appBlockGuide tool. It returns the server's current version of the contract below — always fetch it before building or updating a block.

Copy link

The Sandbox Model

A block is a single, self-contained HTML document — inline CSS and JavaScript, no external scripts, stylesheets, or CDNs. Infa renders it in a sandboxed iframe with allow-scripts only: the block has an opaque origin and no direct network access. It communicates with the host page exclusively via postMessage.

Copy link

Host Protocol (postMessage)

Messages your block receives (listen for message events on window):

Messages your block sends (via window.parent.postMessage(message, "*")):

A minimal skeleton that handles props, escaping, and resize:

<!doctype html>
<style>
    :root { color-scheme: light dark; }
    body { font-family: system-ui, sans-serif; margin: 0; padding: 12px; }
</style>
<div id="root"></div>
<script>
    const root = document.getElementById("root");
    function render(props) {
        // textContent escapes untrusted data — props are user-supplied
        root.textContent = props.label ?? "Set a label via Edit props.";
        parent.postMessage(
            { type: "infa:resize", height: document.body.scrollHeight },
            "*"
        );
    }
    window.addEventListener("message", (event) => {
        if (event.data?.type === "infa:props") render(event.data.props ?? {});
    });
</script>

Copy link

Live Integration Data (the Connector Bridge)

Blocks cannot fetch directly — provider data flows through the host, which proxies each request to the provider's official API with the viewing user's session. Tokens never reach the block.

Send a request:

window.parent.postMessage(
    {
        type: "infa:connector-request",
        requestId: "req-1", // any unique string, echoed back in the response
        connectorId: props.connectorId, // always from a prop — never hardcoded
        request: {
            path: "/repos/owner/repo/pulls?state=open",
            method: "GET", // optional; GET unless the provider needs POST
            body: undefined, // optional JSON body for POST requests
        },
    },
    "*"
);

The host replies with one of:

• { type: "infa:connector-response", requestId, ok: true, data } on success
• { type: "infa:connector-response", requestId, ok: false, error } on failure

Supported provider APIs: GitHub, Figma, and Slack (GET); Notion (GET and POST); Linear (POST /graphql). Requests outside the provider's official API are rejected.

Copy link

Connector Rules

Never hardcode a connectorId or credential. Take the connection as a prop, and declare that prop in inputSchema with "format": "infa-connector-id" — Infa renders it as a dropdown of the board's connections in the props editor:

{
    "type": "object",
    "properties": {
        "connectorId": {
            "type": "string",
            "title": "GitHub connection",
            "format": "infa-connector-id"
        }
    },
    "required": ["connectorId"]
}

Declare the providers you use in contextHints.connections (provider slugs, e.g. ["github"]) so listings badge the block as needing a connection.

Copy link

Lifecycle (Infa MCP Tools)

Owners manage published blocks at infa.ai/profile?tab=blocks.

Copy link

Quality Bar

Before publishing to the community, make sure your block clears the same bar Infa's own blocks do:

• Escape all data you interpolate into HTML (use textContent or an esc() helper) — props and API responses are untrusted.
• Support dark mode: style with CSS custom properties plus @media (prefers-color-scheme: dark).
• Handle the empty state (no props bound yet) with a helpful placeholder that tells the user what to configure.
• Validate props and list required ones in inputSchema.required.
• Never embed credentials, tokens, or personal data in sourceHtml — published blocks are public.

Copy link

Next Steps