---
title: MCP Apps Quickstart Guide
subtitle: Create your first MCP App in minutes
---
This guide walks you through creating your first MCP App using the [Apollo AI Apps Template](https://github.com/apollographql/ai-apps-template). The template provides a complete setup with React, Vite, Apollo Client, and Apollo MCP Server integration.
<Note>
This guide uses ChatGPT as an example, but MCP Apps work with any host that supports the MCP Apps specification.
</Note>
If you're already familiar with building GraphQL apps with Apollo Client, you'll find that building MCP Apps feels very similar. You'll use the same patterns—defining GraphQL operations, using React components, and leveraging Apollo Client's hooks—with the addition of `@tool` and `@prefetch` directives to expose your operations as MCP tools. This means you can apply your existing Apollo Client knowledge with minimal learning curve.
## Prerequisites
Before starting, ensure you have all the [MCP Apps Prerequisites](/apollo-mcp-server/mcp-apps-prerequisites) in place, including:
- An MCP Apps-compatible host (this guide uses ChatGPT as an example)
- Node.js v18 or later (for the template)
- npm or yarn (for the template)
- (Optional) ngrok or similar tunneling tool (for accessing from your host)
## Step 1: Create your app from template
Use the Apollo AI Apps Template to scaffold your project:
```bash
npx tiged apollographql/ai-apps-template my-awesome-app
```
This creates a new directory `my-awesome-app` with all the necessary files and structure.
## Step 2: Navigate and install
Navigate to your new project directory and run the install script:
```bash
cd my-awesome-app
./install.sh
```
The install script sets up all dependencies and configures your project.
## Step 3: Understand the project structure
The template creates a project with the following structure:
```
my-awesome-app/
├── ecommerce-graph/ # Demo GraphQL API
├── dev/
│ └── the-store/ # Your React app (development directory)
├── apps/ # Output directory for the build artifacts
├── mcp-config.yaml # MCP Server configuration
├── schema.graphql # GraphQL schema
└── start_mcp.sh # Script to start MCP server
```
## Step 4: Start the services
You'll need to run three services in separate terminal windows:
### Terminal 1: Start the GraphQL API
```bash
cd ecommerce-graph
npm run dev
```
This starts the demo e-commerce GraphQL API on `http://localhost:4000`.
### Terminal 2: Start your React app
For end-to-end testing with your host (for example, ChatGPT):
```bash
cd dev/the-store
npm run dev:e2e
```
For local development and testing in an emulator:
```bash
cd dev/the-store
npm run dev
```
This builds and serves your React app, which is accessible to the MCP server.
### Terminal 3: Start the MCP server
From the root of your project, run this command:
```bash
./start_mcp.sh
```
That command starts the Apollo MCP Server, which:
- Loads your app's build artifacts from the `apps/` directory
- Connects to your GraphQL API
- Serves your React app as a resource
- Exposes MCP tools to your host (for example, ChatGPT)
## Step 5: Set up tunneling (for host access)
### Configure allowed hosts
After starting ngrok, update your `mcp-config.yaml` file to allow the ngrok domain.
```yaml
transport:
type: streamable_http
stateful_mode: false
host_validation:
allowed_hosts:
- abc123.ngrok-free.app # Replace with your ngrok domain
```
Replace `abc123.ngrok-free.app` with your actual ngrok domain (without the `https://` protocol). If you're using a custom ngrok domain, use that instead.
### Set up tunnel
To access your locally running MCP server from your host (for example, ChatGPT), create a tunnel using ngrok:
```bash
ngrok http 8000
```
That command creates a public URL (for example, `https://abc123.ngrok-free.app`) that tunnels to your local MCP server on port 8000.
<Note>
Make sure to note the HTTPS URL that ngrok provides. You need this in the next step.
</Note>
## Step 6: Connect to your host
Follow your host's documentation to connect your MCP server. For this example using ChatGPT, follow the instructions in the [OpenAI documentation](https://developers.openai.com/apps-sdk/quickstart/#add-your-app-to-chatgpt).
<Note>
For other hosts, reference the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/getting-started/intro).
</Note>
When adding your MCP server URL to your host (for example, ChatGPT) or MCP Inspector, use this format:
```
https://your-ngrok-url.ngrok-free.app/mcp?app=the-store
```
**Important**: Include the `/mcp?app=the-store` query parameter. The `app` parameter tells the MCP server what app to load.
## Step 7: Test your app
Once connected to your host, test your app by invoking your tools. For example, when using ChatGPT, you might ask:
> "Show me the products available"
Your host should:
1. Call your MCP tool
2. Execute the GraphQL query against your API
3. Display the results using your React app's UI
## What you've built
You've created an MCP App (in this example, for ChatGPT) that:
- ✅ Uses React and Vite for a modern development experience
- ✅ Integrates with Apollo Client for GraphQL
- ✅ Executes GraphQL queries when invoked
- ✅ Displays results in a custom React UI
- ✅ Provides a richer experience than plain text
- ✅ Can be extended with more features
## Customizing your app
### Modify the React app
Edit files in your development directory (the template uses `dev/the-store/`) to customize your app's UI and behavior. The app uses:
- **React** for the UI framework
- **Vite** for building and bundling
- **Apollo Client** for GraphQL integration
- **Apollo MCP Server** for MCP Apps integration
<Note>
**Development vs Build Artifacts**: Development happens in your development directory (we recommend using `dev/<app-name>`, as the template does). When you build your app, the build artifacts (including the manifest file) are placed in the `apps/` directory, which is where the MCP Server reads from. Don't edit files directly in `apps/`. Instead, make changes in your development directory.
</Note>
### Update GraphQL operations
Modify the GraphQL operations in your app code. Use the `@tool` directive to define MCP tools and the `@prefetch` directive to mark operations that need to be pre-loaded. The manifest is automatically generated from your app code and your configuration files.
### Change the GraphQL API
Replace the demo `ecommerce-graph` with your own GraphQL API. Update the endpoint in `mcp-config.yaml`:
```yaml
endpoint: http://localhost:4000/ # Your GraphQL API endpoint
```
## Development workflow
### Local development
For local development and testing:
1. Run `npm run dev` in `dev/the-store/` (instead of `npm run dev:e2e`)
2. Use a local emulator or test environment
3. Make changes and see them hot-reload
<Note>
The template comes pre-bundled with MCP Jam for local emulation, so you don't need to set up a host connection yourself for local testing.
</Note>
### End-to-end testing
For testing with your host (for example, ChatGPT):
1. Run `npm run dev:e2e` in `dev/the-store/`
2. Start ngrok tunnel
3. Connect your host to your ngrok URL
4. Test your app in the real host environment
## Next steps
- Review the [MCP Apps Reference](/apollo-mcp-server/mcp-apps-reference) for key concepts and configuration
- Review the [template repository](https://github.com/apollographql/ai-apps-template) for more examples
## Configuration details
### MCP server configuration
The `mcp-config.yaml` file configures your MCP server. Key settings:
```yaml
endpoint: http://localhost:4000/ # Your GraphQL API
transport:
type: streamable_http
stateful_mode: false
port: 8000
host_validation:
allowed_hosts:
- your-ngrok-domain.ngrok-free.app # Required when using ngrok
```
**Important**: When using ngrok, you must add your ngrok domain to `host_validation.allowed_hosts` to prevent DNS rebinding attacks. See Step 5 for details.
### App query parameter
When connecting to your MCP server, use the `app` query parameter to specify which app to load:
- `?app=the-store` - Loads the app named "the-store"
- The app name corresponds to the directory name
### App target
By default, Apollo MCP Server uses the AppsSDK target (for example, for ChatGPT). You can also specify it explicitly:
```
https://your-url.ngrok-free.app/mcp?app=the-store&appTarget=openai
```
### App configuration
App-level configuration (like CSP settings, widget settings, and labels) can be defined in a configuration file or in `package.json`. The system uses `cosmiconfig` to automatically detect and load configuration from:
- `.apollo-client-ai-apps.config.json`
- `apollo-client-ai-apps.config.json`
- `.apollo-client-ai-apps.config.yml` / `.yaml`
- `apollo-client-ai-apps.config.yml` / `.yaml`
- `.apollo-client-ai-apps.config.js` / `.ts` / `.cjs`
- `apollo-client-ai-apps.config.js` / `.ts` / `.cjs`
- An `apollo-client-ai-apps` key in `package.json`
