---
title: MCP Apps Architecture
subtitle: How MCP Apps work with Apollo MCP Server
---

MCP Apps combine GraphQL operations with custom UI resources to create interactive experiences in MCP Apps-compatible hosts. Apollo MCP Server bridges your GraphQL APIs to the MCP Apps specification.

## High-level flow

MCP Apps work in two phases:

**Discovery phase**: The host discovers your app and pre-fetches the built resource.

**Tool execution phase**: When a tool is invoked, the host receives data from the MCP server and injects it into a pre-loaded iframe.

```mermaid
graph TB
    subgraph Discovery["Discovery Phase"]
        Host1["MCP Apps Host"]
        MCPServer1["Apollo MCP Server"]
        
        Host1 -->|"1. List Resources"| MCPServer1
        MCPServer1 -->|"2. Return Resource URI"| Host1
        Host1 -->|"3. Read Resource"| MCPServer1
        MCPServer1 -->|"4. Return UI Content"| Host1
    end
    
    subgraph Execution["Tool Execution Phase"]
        Host2["MCP Apps Host"]
        MCPServer2["Apollo MCP Server"]
        GraphQL["GraphQL API"]
        Iframe["Iframe with UI"]
        
        Host2 -->|"5. Invoke Tool"| MCPServer2
        MCPServer2 -->|"6. Execute GraphQL"| GraphQL
        GraphQL -->|"7. Return Data"| MCPServer2
        MCPServer2 -->|"8. Return Data"| Host2
        Host2 -->|"9. Create Iframe"| Iframe
        Host2 -->|"10. Inject Data"| Iframe
    end
    
    style Host1 fill:#E3F2FD
    style Host2 fill:#E3F2FD
    style MCPServer1 fill:#1976D2,color:#fff
    style MCPServer2 fill:#1976D2,color:#fff
    style GraphQL fill:#00ACC1,color:#fff
    style Iframe fill:#4CAF50,color:#fff
```

When an MCP Apps-compatible host invokes a tool, Apollo MCP Server executes the GraphQL operation and returns only the data. The host then creates an iframe with the pre-fetched HTML resource and injects the tool result data into it.

## App components

An MCP App consists of:

- **Tools**: GraphQL operations exposed as MCP tools that MCP Apps-compatible hosts can invoke
- **Resource**: The built `.html` file that contains your application code.

The app manifest (`.application-manifest.json`) is automatically generated from your app code and your configuration file (or `package.json`). GraphQL operations come from your app code, while app-level configuration comes from your configuration files. The manifest defines the mapping between tools, operations, and the resource.

## App structure

Apps are organized in directories under `apps/`, each containing build artifacts (the manifest file and built resources). The MCP Server reads from the `apps/` directory.

**Important**: The `apps/` directory contains build artifacts, not your development code. Development happens in a separate directory (we recommend using `dev/<app-name>`, like the [Apollo AI Apps Template](https://github.com/apollographql/ai-apps-template) does).


## Resources

The resource is the built `.html` file that contains your application code. This file is loaded by the host and contains everything needed to render your app's UI. We recommend using the [Apollo AI Apps Template](https://github.com/apollographql/ai-apps-template) for a complete setup.

## App target selection

Apollo MCP Server supports two app targets:
- ChatGPT Apps: For hosts that support OpenAI's Apps SDK specification (for example, ChatGPT)
- MCP Apps: MCP Apps-compatible clients

The target determines MIME type, metadata format, and CSP format.
