In an effort to improve user experience and accessibility of our documentation, we are excited to introduce an experimental feature: the Docs Chatbot. This makes it easy to help users find answers to their questions more efficiently by leveraging the Mastra MCP Docs server.
The Challenge
We noticed a recurring issue: many users were asking questions on our Discord that were already answered in our documentation. However, finding these answers wasn't always straightforward. Our goal was to create a solution that would make it easier for users to access the information they need without having to sift through extensive documentation manually.
The Solution: Docs Chatbot
The Docs Chatbot is a new feature that utilizes our Mastra MCP Docs server to retrieve information from our documentation, examples, and blog posts. This agent is deployed on Mastra Cloud and interacts with our docs website through the Mastra Client, providing a seamless and efficient user experience.
Key Features
- CopilotKit Integration: We have integrated CopilotKit for the chat interface, ensuring a smooth and user-friendly chat experience.
- Real-time Information Retrieval: The chatbot can access the complete Mastra documentation, code examples, and blog posts, providing users with accurate and up-to-date information.
- Experimental and Community-Driven: While it's currently labeled as experimental, we are eager to receive feedback from the community while continuing to make improvements.
How we built it
First we set up the MCP Client to connect to the Mastra docs server:
1// /src/mastra/mcp-config.ts
2import { MCPClient } from "@mastra/mcp";
3
4// Create an MCP configuration for the Mastra docs server
5export const docsMcp = new MCPClient({
6 id: "mastra-docs", // Unique identifier to prevent memory leaks
7 servers: {
8 mastraDocs: {
9 // Using npx to run the Mastra docs server
10 command: "npx",
11 args: ["-y", "@mastra/mcp-docs-server@latest"],
12 },
13 },
14});Next we set up the Mastra agent that uses the MCP Client:
1// /src/mastra/agents/docs-agent.ts
2import { openai } from '@ai-sdk/openai';
3import { Agent } from '@mastra/core/agent';
4import { docsMcp } from '../mcp-config';
5import { linkCheckerTool } from '../tools/link-checker';
6
7const tools = await docsMcp.getTools();
8
9export const docsAgent = new Agent({
10 name: 'docsAgent',
11 instructions:
12 // Persistence reminder - ensures the model keeps going through multi-step process
13 'You are a helpful assistant specialized in Mastra documentation and usage. ' +
14 "You are an agent - please keep going until the user's query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved. " +
15 // Tool-calling reminder - encourages proper use of available tools
16 'You have access to the complete Mastra documentation, code examples, blog posts, and package changelogs through your tools. ' +
17 "If you are not sure about specific Mastra features, documentation, or codebase structure pertaining to the user's request, use your tools to search and gather the relevant information: do NOT guess or make up an answer. " +
18 // Planning reminder - ensures thoughtful approach before tool use
19 'You MUST plan extensively before each tool call, and reflect extensively on the outcomes of the previous tool calls. This will help you provide more accurate and helpful information. ' +
20 "Don't answer questions about Mastra that are not related to the documentation or codebase. If you are not sure about the user's question, say so. " +
21 "Don't answer questions unrelated to Mastra. If you are not sure about the user's question, say so. " +
22 // [check repo for full instructions...]
23 "",
24 model: openai('gpt-4.1'),
25 tools: {
26 ...tools,
27 linkCheckerTool,
28 },
29});Then we set up the CopilotKit UI. We started with setting up the API route:
1// /src/app/api/copilotkit/route.ts
2import {
3 CopilotRuntime,
4 ExperimentalEmptyAdapter,
5 copilotRuntimeNextJSAppRouterEndpoint,
6} from "@copilotkit/runtime";
7import { NextRequest } from "next/server";
8import { MastraClient } from "@mastra/client-js";
9
10const baseUrl = process.env.MASTRA_AGENT_URL || "http://localhost:4111";
11
12const client = new MastraClient({
13 baseUrl,
14});
15
16export const POST = async (req: NextRequest) => {
17 const runtime = new CopilotRuntime({
18 agents: await client.getAGUI({ resourceId: "docsAgent" }),
19 });
20
21 const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
22 runtime,
23 serviceAdapter: new ExperimentalEmptyAdapter(),
24 endpoint: "/api/copilotkit",
25 });
26
27 return handleRequest(req);
28};Now we could set up the ChatWidget. You can view the full ChatWidget source code.
1// /src/chatbot/components/chat-widget.tsx
2const DocsChat: React.FC<{
3 setIsAgentMode: (isAgentMode: boolean) => void;
4 searchQuery: string;
5}> = ({ setIsAgentMode, searchQuery }) => {
6 return (
7 <CopilotKit
8 runtimeUrl="/api/copilotkit"
9 showDevConsole={false}
10 // agent lock to the relevant agent
11 agent="docsAgent"
12 >
13 <CustomChatInterface
14 setIsAgentMode={setIsAgentMode}
15 searchQuery={searchQuery}
16 />
17 </CopilotKit>
18 );
19};Try it out!
Please try out the Docs Chatbot and share your thoughts with us on Discord.