mcp -workshop

The Mastra MCP Server Workshop provides a local MCP server that serves markdown notes from a local directory, exposes tools for the agent to create and edit those notes, and pairs with a reactive Next.js frontend to present and manipulate the content. The server is designed to illustrate how to build custom agent tools (like writeNote) and prompts, and how to push updates to a client in real time. In practice, you can run the MCP server separately from the frontend and the agent, reflecting a typical production setup where services are decoupled. Once running, you can interact with the agent through slash-command prompts to create notes, edit content, and trigger predefined prompts such as brainstorming ideas or summarizing a note. The frontend offers a list of notes, a note viewer, and an agent panel that uses these server capabilities to manage your local markdown repository.

Prerequisites:

• Node.js and pnpm installed on your machine
• Access to a terminal/command prompt

Install dependencies (from the repository root):

pnpm install

Run the MCP server (separate from the frontend and agent):

pnpm dev:mcp

Run the Mastra agent (optional, to demonstrate the agent interacting with the MCP server):

pnpm dev:agent

Run the frontend (Next.js app):

pnpm dev:web

Open the application in your browser at http://localhost:3000

Notes:

• The MCP server exposes markdown notes from the local packages/notes directory. Ensure the directory exists and contains your initial notes.
• The agent has a writeNote tool to create or modify notes on the filesystem. Use descriptive titles and content to see updates reflected in real-time.
• The frontend includes a slash-command menu. Type / in the agent chat to bring up prompts like brainstorm_ideas or summarize_note. Prompts operate using the current note context when available.
• In a production workflow, run the MCP server and agent separately; the agent should be configured to reach the MCP server endpoint. This separation mirrors typical service-oriented architectures and improves reliability during development.
• If you modify notes outside of the MCP tools, you may need to refresh the frontend to see changes reflected in the UI.