Template: Docs Chatbot with MCP Server

This template demonstrates how to build a documentation chatbot using MCP (Model Control Protocol) servers with Mastra. It shows how to define and consume an MCP server that provides tools for interacting with your documentation.

🎯 What This Template Shows

This template illustrates the complete MCP workflow:

Define an MCP Server - Creates tools that can interact with your documentation
Consume the MCP Server - Connects to the server to use those tools
Agent Integration - Uses an agent that can leverage the MCP tools

In this example, the "documentation" is planet data, but you can easily replace this with your own documentation source (APIs, databases, files, etc.).

🔧 What is MCP?

Model Control Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. It allows you to:

Create reusable tools that any MCP-compatible client can use
Securely expose your data and APIs to AI agents
Build modular, interoperable AI systems

🏗️ Project Structure

 1src/
 2├── data/
 3│   └── functions.json          # Sample documentation data
 4├── mastra/
 5│   ├── agents/
 6│   │   └── kepler-agent.ts  # Agent that uses MCP tools
 7│   ├── mcp/
 8│   │   ├── mcp-client.ts     # Client to connect to MCP server
 9│   │   └── mcp-server.ts     # MCP server definition
10│   ├── tools/
11│   │   └── docs-tool.ts   # Tool for querying Kepler function data
12│   └── index.ts              # Main Mastra configuration
13└── scripts/
14    └── mcp-server-http.ts    # Standalone MCP server runner

🚀 Quick Start

1. Install Dependencies

pnpm install

2. Environment Variables

Create a .env file in the root directory:

 1# Optional: Customize server URLs (defaults work for local development)
 2MCP_SERVER_URL=http://localhost:4111/mcp
 3SERVER_BASE_URL=http://localhost:4111
 4
 5# Optional: Set to production for HTTPS in deployed environments
 6NODE_ENV=development

3. Run the Application

 1# Start the Mastra server (includes MCP server)
 2pnpm dev
 3
 4# Or run the standalone MCP server
 5pnpm run mcp-server

4. Test the Setup

The server will start on http://localhost:4112 with these endpoints:

Health Check: GET /health
MCP Info: GET /mcp/info
MCP Endpoint: GET /mcp (Server-Sent Events)

🛠️ How It Works

MCP Server (`src/mastra/mcp/mcp-server.ts`)

The MCP server exposes tools that can interact with your documentation:

 1export const mcpServer = new MCPServer({
 2  name: 'Template Docs Chatbot MCP Server',
 3  tools: {
 4    keplerInfoTool, // Your documentation query tool
 5  },
 6});

MCP Client (`src/mastra/mcp/mcp-client.ts`)

The client connects to the MCP server to use its tools:

 1export const mcpClient = new MCPClient({
 2  servers: {
 3    localTools: {
 4      url: new URL(process.env.MCP_SERVER_URL || 'http://localhost:4111/mcp'),
 5    },
 6  },
 7});

Documentation Tool (`src/mastra/tools/docs-tool.ts`)

Query documentation for Kepler project functions with their arguments:

 1export const keplerInfoTool = createTool({
 2  id: 'docs-tool',
 3  description: 'Get detailed information about Kepler project functions, including arguments and helpful tips',
 4  // ... tool configuration
 5});

Agent (`src/mastra/agents/kepler-agent.ts`)

The Kepler Documentation Agent that can answer questions about available functions:

 1export const keplerAgent = new Agent({
 2  name: 'Kepler Documentation Agent',
 3  instructions: 'You are a helpful assistant that provides information about Kepler project functions.',
 4  // ... agent configuration
 5});

🔄 Customizing for Your Documentation

To adapt this template for your own documentation:

1. Replace the Data Source

Update src/data/functions.json with your documentation data (including function arguments)
Or connect to your API, database, or file system

2. Modify the Tool

Edit src/mastra/tools/docs-tool.ts:

 1export const myDocsInfoTool = createTool({
 2  id: 'my-docs-info',
 3  description: 'Search and retrieve information from my documentation',
 4  inputSchema: z.object({
 5    query: z.string().describe('Search query for documentation'),
 6  }),
 7  execute: async ({ context, input }) => {
 8    // Implement your documentation search logic
 9    const results = await searchMyDocs(input.query);
10    return { results };
11  },
12});

3. Update the Agent

Modify src/mastra/agents/kepler-agent.ts:

 1export const myDocsAgent = new Agent({
 2  name: 'myDocsAgent',
 3  instructions:
 4    'You are a helpful assistant that provides information from our documentation. Use the available tools to search and retrieve relevant information.',
 5  model: {
 6    provider: 'ANTHROPIC',
 7    name: 'claude-3-5-sonnet-20241022',
 8  },
 9  tools: await mcpClient.getTools(),
10});

4. Register Your Changes

Update src/mastra/index.ts:

 1export const mastra = new Mastra({
 2  agents: {
 3    myDocsAgent, // Your agent
 4  },
 5  mcpServers: {
 6    myDocs: mcpServer, // Your MCP server
 7  },
 8  // ... rest of configuration
 9});

🌐 Deployment

This template is configured to work in both local and production environments:

Environment Variables for Production

 1MCP_SERVER_URL=https://your-app.com/mcp
 2SERVER_BASE_URL=https://your-app.com
 3NODE_ENV=production

📡 API Endpoints

Health Check

GET /health

Returns server status and available services.

MCP Information

GET /mcp/info

Returns information about the MCP server and available tools.

MCP Server-Sent Events

GET /mcp

The main MCP endpoint for tool communication.

🔧 Development

Available Scripts

 1# Start the main Mastra server
 2pnpm start
 3
 4# Run standalone MCP server
 5pnpm run mcp-server
 6
 7# Development mode with hot reload
 8pnpm dev

Adding New Tools

Create a new tool in src/mastra/tools/
Register it in the MCP server (src/mastra/mcp/mcp-server.ts)
The agent will automatically have access to use it

📚 Learn More

🤝 Contributing

This is a template - feel free to fork it and adapt it for your needs! If you create improvements that could benefit others, consider contributing back.