> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/mcp-apps.md).

# MCP Interactive Cards (MCP Apps)

How interactive cards (MCP Apps) provided by MCP servers appear and work in Web Chat and MaiGPT conversations, their requirements and security restrictions, suitable use cases, and frequently asked qu

Some MCP servers return an interactive interface along with data. After an Agent calls one of these tools, a card appears in the conversation that users can interact with directly, such as a table of query results or a form with checkboxes or input fields. This lets users do more than exchange text messages.

The MCP server determines how the card looks and what it can do. MaiAgent displays it safely in the conversation and forwards actions on the card to the same MCP server. To add interactive cards to your own system, ask your engineers to refer to [Self-hosted MCP Server: MCP Apps](https://docs.maiagent.ai/tech/mcp/self-hosted-mcp-server#mcp-apps) and the [minimal runnable example](https://docs.maiagent.ai/tech/mcp/self-hosted-mcp-server#mcp-apps-example) in the technical guide.

## What Users See <a href="#mcp-apps-what-users-see" id="mcp-apps-what-users-see"></a>

| Scenario                             | Behavior                                                                                                                                                                                                                                                                                 |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where the card appears               | The card appears below the Agent's reply once the reply is complete (it does not appear while the reply is still being generated)                                                                                                                                                        |
| Loading                              | When the card first appears, it shows its own loading screen (such as “Loading…”), then switches to the actual content once the data arrives                                                                                                                                             |
| Multiple calls in the same turn      | Only the latest state of the same card is displayed; multiple identical cards do not appear                                                                                                                                                                                              |
| Interacting with the card            | Buttons and forms on the card can query or submit data directly, and results update within the same card                                                                                                                                                                                 |
| Card height                          | Adjusts automatically to the content; when the content exceeds about 60% of the screen height (up to 620px), it scrolls within the card                                                                                                                                                  |
| Full screen                          | If the card provides a full-screen button, you can expand it to full screen. Click ✕ in the upper right (<mark style="color:blue;">Exit full screen and return to the conversation</mark>) or press Esc to return to the conversation. The card keeps the height it had before expansion |
| Asking AI from the card              | If the card provides a question feature, the submitted content appears in the conversation as a user message. The card automatically collapses back into the conversation, and the Agent answers next                                                                                    |
| Opening external links from the card | The browser opens a new tab; only standard web, telephone, and Email links are opened                                                                                                                                                                                                    |
| Dark mode and brand colors           | The platform tells the card the current light/dark mode and brand colors; the card decides whether to apply them                                                                                                                                                                         |
| Card content fails to load           | The summary returned by the tool is displayed as plain text instead                                                                                                                                                                                                                      |

Cards appear in [Web Chat](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat.md) and [MaiGPT](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt.md) conversations. Other messaging platforms, such as LINE and Messenger, do not display cards; users receive the Agent's text reply.

{% hint style="info" %}
Cards are unaffected by the “Display mode” in [Custom Tool Message Display](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/tool-display-settings.md#choose-display-mode): interactive cards still appear even when “Hide” is selected. “Hide” applies only to the tool execution block.
{% endhint %}

### Reopening a Conversation <a href="#mcp-apps-history" id="mcp-apps-history"></a>

The card's interface and the tool results at the time are saved with the message. When you later reopen the conversation from its history:

* The card reappears with **the tool results from that time**. Partially completed fields or new results from subsequent queries within the card are not retained.
* The card's buttons remain usable as long as the MCP tool or connector is still configured for the conversation and its authorization remains valid. Otherwise, “This action could not be completed. Please try again later.” appears.
* Later updates to the card interface on the MCP server do not change cards already generated in historical messages.

## Requirements <a href="#mcp-apps-requirements" id="mcp-apps-requirements"></a>

1. **The MCP server provides an interactive interface**: The tool definition or returned result must include an interface resource starting with `ui://`. The MCP server decides whether to provide it; no additional switch is needed in MaiAgent. For self-hosted MCP servers, see [Self-hosted MCP Server](https://docs.maiagent.ai/tech/mcp/self-hosted-mcp-server#mcp-apps) in the technical guide.
2. **The Agent can access this MCP server**: Configure it as an [MCP tool](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/mcp-setup.md) for an Agent whose response mode is Agent mode, or have a member authorize it through [connectors](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt/connectors.md) in MaiGPT.
3. **The conversation takes place in Web Chat or MaiGPT**. Availability of interactive cards in on-premises Web Chat depends on the deployment settings. Contact your MaiAgent representative to confirm.

## Suitable Use Cases for Interactive Cards <a href="#mcp-apps-use-cases" id="mcp-apps-use-cases"></a>

Cards work well for results that are difficult to convey in text or require user interaction. Common examples include:

| Scenario                                     | What the card does                                                                                                                                              | Limitations of text replies                                                                          |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Tables and charts of query results           | Displays order, inventory, report, and other query results in tables or charts, with sorting or date-range selection                                            | Multiple fields and records are difficult to read when listed in text                                |
| Filling out forms                            | Lets users fill in fields for leave requests, repair requests, and similar forms directly on the card; the same MCP server creates the request after submission | Collecting each field through questions and answers can lead to missing entries or incorrect formats |
| Confirming submission                        | Lists content prepared by the Agent (such as a notification to send or settings to change), and performs the action only after the user clicks “Confirm”        | Users can only reply “OK” in text, making it harder to see exactly what will be done                 |
| Selecting a map location, date, or time slot | Lets users select a store, appointment slot, or seat, then passes the selection back to the Agent                                                               | Locations and time slots are inconvenient to describe and compare in text                            |

The shared principle: a card handles only actions associated with this particular tool result. The Agent's conversation still connects workflows with multiple steps.

## Security and Limitations <a href="#mcp-apps-security" id="mcp-apps-security"></a>

* Cards run in an isolated sandbox frame. They cannot read the login state or data of the MaiAgent page and, by default, cannot connect to external websites on their own.
* Actions within a card can only call tools from the card's source MCP server that are already available to the conversation. They use the same authorization method as the Agent's calls to that server. An action that receives no response within 30 seconds is treated as failed.
* If an external link requested by the card is not allowed, “This link cannot be opened.” appears. If the browser blocks a pop-up window, allow pop-ups and try again.

## Frequently Asked Questions <a href="#mcp-apps-faq" id="mcp-apps-faq"></a>

#### The card displays “This action could not be completed. Please try again later.”? <a href="#mcp-apps-action-failed" id="mcp-apps-action-failed"></a>

An action within the card failed or timed out while calling the MCP server, or the tool is no longer available to this conversation. Click <mark style="color:blue;">Retry</mark> to reload the card. If the issue persists, confirm that the MCP server is operating normally, the tool is still configured for the Agent, and the authorization remains valid.

#### The card displays “The interactive component failed to load. Please refresh the page and try again.”? <a href="#mcp-apps-load-failed" id="mcp-apps-load-failed"></a>

The card's interface did not load successfully. Refresh the page or click <mark style="color:blue;">Retry</mark>. If the card stays on its own loading screen, refresh the page first as well.

#### The Agent called an MCP tool, but no card appeared? <a href="#mcp-apps-no-card" id="mcp-apps-no-card"></a>

The tool's MCP server did not provide an interactive interface, or this call returned an error. Only successful tool calls that include a `ui://` interface resource produce a card. Also confirm that you are viewing the conversation in Web Chat or MaiGPT and that the Agent's reply has finished generating.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/mcp-apps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
