MCP Apps Quickstart Guide

This guide walks you through creating your first MCP App using the Apollo AI Apps Template. The template provides a complete setup with React, Vite, Apollo Client, and Apollo MCP Server integration.

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 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:

1npx 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:

1cd my-awesome-app
2./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:

1my-awesome-app/
2├── ecommerce-graph/          # Demo GraphQL API
3├── dev/
4│   └── the-store/            # Your React app (development directory)
5├── apps/                      #  Output directory for the build artifacts
6├── mcp-config.yaml           # MCP Server configuration
7├── schema.graphql             # GraphQL schema
8└── 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

1cd ecommerce-graph
2npm 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):

1cd dev/the-store
2npm run dev:e2e

For local development and testing in an emulator:

1cd dev/the-store
2npm 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:

1./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.

1transport:
2  type: streamable_http
3  stateful_mode: false
4  host_validation:
5    allowed_hosts:
6      - 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:

1ngrok 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.

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.

When adding your MCP server URL to your host (for example, ChatGPT) or MCP Inspector, use this format:

1https://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

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:

1endpoint: 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

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 for key concepts and configuration

• Review the template repository for more examples

Configuration details

MCP server configuration

The mcp-config.yaml file configures your MCP server. Key settings:

1endpoint: http://localhost:4000/  # Your GraphQL API
2transport:
3  type: streamable_http
4  stateful_mode: false
5  port: 8000
6  host_validation:
7    allowed_hosts:
8      - 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:

1https://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