What is Epic Mcp

epic-mcp is an example of the Epic Stack that provides a /mcp endpoint, designed to help teams quickly ship web applications based on best practices and experiences from industry experts.

Use cases

Use cases for epic-mcp include developing single-page applications (SPAs), creating APIs, and building full-stack applications that require rapid deployment and iterative development.

How to use

To use epic-mcp, you can initiate a new project by running the command ‘npx create-epic-app@latest’ in your terminal, which sets up the project structure and dependencies for you.

Key features

Key features of epic-mcp include a streamlined project setup, a focus on stability and performance, and a community-driven approach that encourages collaboration and sharing of ideas.

Where to use

epic-mcp can be used in web development projects, particularly for building scalable and maintainable web applications that require a solid foundation.

Epic MCP

An Epic Stack example adding
support for the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how
applications provide context to Large Language Models (LLMs). Think of MCP like
a USB-C port for AI applications - it provides a standardized way to connect AI
models to different data sources and tools.

Learn more from the
MCP Documentation

Example Implementation

This repository demonstrates how to integrate MCP into an Epic Stack
application. The implementation includes:

1. Server-side MCP setup for handling client connections
2. SSE (Server-Sent Events) transport layer for real-time communication
3. Example tool implementations showing how to expose functionality to LLMs

Key Components

1. MCP Server Setup (app/routes/mcp+/mcp.server.ts)

export const server = new McpServer(
	{
		name: 'epic-mcp-a25d',
		version: '1.0.0',
	},
	{
		capabilities: {
			tools: {},
		},
	},
)

The MCP server is the core component that handles tool registration and
execution. It’s configured with a unique name and version, and defines the
capabilities it provides.

2. Tool Implementation

server.tool(
	'Find User',
	'Search for users in the Epic Notes database by their name or username',
	{ query: z.string().describe('The query to search for') },
	async ({ query }) => {
		// Implementation...
	},
)

Tools are the primary way to expose functionality to LLMs. Each tool:

• Has a descriptive name and purpose
• Uses Zod for type-safe parameter validation
• Can return multiple content types (text, images, etc.)
• Integrates with your existing application logic

3. Transport Layer (app/routes/mcp+/fetch-transport.server.ts)

The transport layer handles the bi-directional communication between the MCP
client and server:

• Uses Server-Sent Events (SSE) for real-time server-to-client communication
• Handles POST requests for client-to-server messages
• Maintains session state for multiple concurrent connections

4. Route Integration (app/routes/mcp+/index.ts)

export async function loader({ request }: Route.LoaderArgs) {
	const url = new URL(request.url)
	const sessionId = url.searchParams.get('sessionId')
	const transport = await connect(sessionId)
	return transport.handleSSERequest(request)
}

The Remix route:

• Establishes SSE connections for real-time communication
• Handles incoming tool requests via POST endpoints
• Manages session state for multiple clients

Learning Points

1. Tool Design: When designing tools for LLMs:

   • Provide clear, descriptive names and purposes
   • Use strong type validation for parameters
   • Return structured responses that LLMs can understand
   • Consider supporting multiple content types (text, images, etc.)

2. State Management: The implementation demonstrates:

   • Session-based connection tracking
   • Clean connection cleanup on client disconnect
   • Safe concurrent client handling

3. Integration Patterns: Learn how to:

   • Connect MCP with existing application logic
   • Handle real-time communication in Remix
   • Structure your MCP implementation for maintainability

4. Security Considerations:

   • Session-based access control
   • Safe handling of client connections
   • Proper cleanup of resources