Skip to content
Back to search

mcp-agent-langchainjs

Serverless AI agent using LangChain.js and Model Context Protocol (MCP) integration to order burgers from a burger restaurant

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/azure-samples--mcp-agent-langchainjs/badge.svg)](/listings/azure-samples--mcp-agent-langchainjs)

HTML

<a href="/listings/azure-samples--mcp-agent-langchainjs"><img src="/api/listings/azure-samples--mcp-agent-langchainjs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

There are multiple ways to get started with this project. The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.

<details open> <summary><h3>Use GitHub Codespaces</h3></summary>

You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:

</details>

<details> <summary><h3>Use a VSCode dev container</h3></summary>

A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

You will also need to have [Docker](https://www.docker.com/get-started/) installed on your machine to run the container.

</details>

<details> <summary><h3>Use your local environment</h3></summary>

You need to install following tools to work on your local machine:

- [Node.js LTS](https://nodejs.org/en/download) - [Azure Developer CLI 1.19+](https://aka.ms/azure-dev/install) - [Git](https://git-scm.com/downloads) - [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_ - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell. - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.

Then you can get the project code:

1. [**Fork**](https://github.com/Azure-Samples/mcp-agent-langchainjs/fork) the project to create your own copy of this repository. 2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.

3. Open a terminal and run this command to clone the repo: `git clone <your-repo-url>`

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 414 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./packages/agent-webapp/public/favicon.png" alt="" align="center" height="64" />
  3. # AI Agent with MCP tools using LangChain.js
  4. [![Open in Codespaces](https://img.shields.io/badge/Codespaces-Open-blue?style=flat-square&logo=github)](https://codespaces.new/Azure-Samples/mcp-agent-langchainjs?hide_repo_select=true&ref=main&quickstart=true)
  5. [![Join Microsoft Foundry Community Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry-blue?style=flat-square&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
  6. [![Deployment time](https://img.shields.io/badge/Deployment-15min-teal?style=flat-square)](#deploy-to-azure)
  7. <br>
  8. [![Build Status](https://img.shields.io/github/actions/workflow/status/Azure-Samples/mcp-agent-langchainjs/build-test.yaml?style=flat-square&label=Build)](https://github.com/Azure-Samples/mcp-agent-langchainjs/actions)
  9. [![dev.to blog post walkthrough](https://img.shields.io/badge/Blog%20post-black?style=flat-square&logo=dev.to)](https://dev.to/azure/serverless-mcp-agent-with-langchainjs-v1-burgers-tools-and-traces-25oo)
  10. ![Node version](https://img.shields.io/badge/Node.js->=22-3c873a?style=flat-square)
  11. [![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
  12. [![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
  13. ⭐ If you like this sample, star it on GitHub — it helps a lot!
  14. [Overview](#overview) • [Architecture](#architecture) • [Getting started](#getting-started) • [Deploy to Azure](#deploy-to-azure) • [Run locally](#run-locally) • [MCP tools](#mcp-tools) • [Resources](#resources)
  15. ![Animation showing the agent in action](./docs/images/demo.gif)
  16. </div>
  17. > [!IMPORTANT]
  18. > 👉 **Follow the [full-length workshop](https://aka.ms/ws/mcp-agent)** to learn how we built this sample.
  19. ## Overview
  20. This project demonstrates how to build AI agents that can interact with real-world APIs using the **Model Context Protocol (MCP)**. It features a complete burger ordering system with a serverless API, web interfaces, and an MCP server that enables AI agents to browse menus, place orders, and track order status. The agent uses **LangChain.js** to handle LLM reasoning and tool calling. The system consists of multiple interconnected services, as detailed in the [Architecture](#architecture) section below.
  21. The system is hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview) (web apps) and [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript) (API and MCP servers), with [Azure Cosmos DB for NoSQL](https://learn.microsoft.com/azure/cosmos-db/nosql/) for data storage. You can use it as a starting point for building your own AI agents.
  22. > [!TIP]
  23. > You can test this application locally without deployment needed or any cloud costs. The MCP server also works with popular AI tools like GitHub Copilot, Claude, and other MCP-compatible clients. Follow the instructions in the [Local Development](#use-ollama-for-local-development) section to get started.
  24. ### Key features
  25. - LangChain.js agent with tool calling via MCP (Streamable HTTP transport)
  26. - Multi-service, end‑to‑end architecture (web UIs, APIs, MCP server)
  27. - User authentication with sessions history
  28. - 100% serverless architecture, for cost-effective scaling
  29. - Single-command deployment using Infrastructure as Code (IaC)
  30. ## Architecture
  31. Building AI applications can be complex and time-consuming, but using LangChain.js and Azure serverless technologies allows to greatly simplify the process. This application is a AI agent that can be access through different interfaces (web app, CLI) and that can call tools through MCP to interact with a burger ordering API.
  32. ![Architecture diagram](docs/images/architecture.drawio.png?raw=true)
  33. The application is made from these main components:
  34. | Component | Folder | Purpose |
  35. | ----------------- | ---------------------------------------------------- | -------------------------------------------- |
  36. | Agent Web App | [`packages/agent-webapp`](./packages/agent-webapp) | Chat interface + conversation rendering |
  37. | Agent API | [`packages/agent-api`](./packages/agent-api) | LangChain.js agent + chat state + MCP client |
  38. | Burger API | [`packages/burger-api`](./packages/burger-api) | Core burger & order management web API |
  39. | Burger MCP Server | [`packages/burger-mcp`](./packages/burger-mcp) | Exposes burger API as MCP tools |
  40. | Burger Web App | [`packages/burger-webapp`](./packages/burger-webapp) | Live orders visualization |
  41. | Infrastructure | [`infra`](./infra) | Bicep templates (IaC) |
  42. Additionally, these optional and support components are included:
  43. | Component | Folder | Purpose |
  44. | --------------- | ------------------------------------------------ | -------------------------------------------------------- |
  45. | Beer MCP Server | [`packages/beer-mcp`](./packages/beer-mcp) | AI-powered beer recommendations via hybrid RAG |
  46. | Agent CLI | [`packages/agent-cli`](./packages/agent-cli) | Command-line interface LangChain.js agent and MCP client |
  47. | Data generation | [`packages/burger-data`](./packages/burger-data) | Scripts to (re)generate burgers data & images |
  48. ## Getting started
  49. There are multiple ways to get started with this project. The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below.
  50. <details open>
  51. <summary><h3>Use GitHub Codespaces</h3></summary>
  52. You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:
  53. [![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=flat-square&label=GitHub+Codespaces&message=Open&color=blue&logo=github)](https://codespaces.new/Azure-Samples/mcp-agent-langchainjs?hide_repo_select=true&ref=main&quickstart=true)
  54. </details>
  55. <details>
  56. <summary><h3>Use a VSCode dev container</h3></summary>
  57. A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
  58. You will also need to have [Docker](https://www.docker.com/get-started/) installed on your machine to run the container.
  59. [![Open in Dev Containers](https://img.shields.io/static/v1?style=flat-square&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/mcp-agent-langchainjs)
  60. </details>
  61. <details>
  62. <summary><h3>Use your local environment</h3></summary>
  63. You need to install following tools to work on your local machine:
  64. - [Node.js LTS](https://nodejs.org/en/download)
  65. - [Azure Developer CLI 1.19+](https://aka.ms/azure-dev/install)
  66. - [Git](https://git-scm.com/downloads)
  67. - [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_
  68. - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
  69. - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
  70. Then you can get the project code:
  71. 1. [**Fork**](https://github.com/Azure-Samples/mcp-agent-langchainjs/fork) the project to create your own copy of this repository.
  72. 2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository.
  73. ![Screenshot showing how to copy the repository URL](./docs/images/clone-url.png)
  74. 3. Open a terminal and run this command to clone the repo: `git clone <your-repo-url>`
  75. </details>
  76. ## Deploy to Azure
  77. ### Prerequisites
  78. - **Azure account**: If you're new to Azure, [get an Azure account for free](https://aka.ms/devrelft) to get free Azure credits to get started
  79. - **Azure account permissions**: Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner)
  80. ### Deploy with Azure Developer CLI
  81. 1. Open a terminal and navigate to the root of the project
  82. 2. Authenticate with Azure by running `azd auth login`
  83. 3. Run `azd up` to deploy the application to Azure. This will provision Azure resources and deploy all services
  84. - You will be prompted to select a base location for the resources
  85. - The deployment process will take a few minutes
  86. Once deployment is complete, you'll see the URLs of all deployed services in the terminal.
  87. > [!IMPORTANT]
  88. > If you're using an Azure for Students or Free Trial account that you just created, you need to run the following command before running `azd up` or else the deployment will fail:
  89. > ```sh
  90. > azd env set AZURE_OPENAI_MODEL_CAPACITY 1
  91. > ```
  92. > This ensures that the resources deployed will fit within the free tier limits. **This limitations reduce the capacity for AI models usage, so you'll also have to provide another OpenAI endpoint to use the application properly.** To do that, use the following commands to set the OpenAI endpoint, API key and model you want to use:
  93. > ```sh
  94. > azd env set AZURE_OPENAI_ALT_ENDPOINT <your_openai_endpoint>
  95. > azd env set AZURE_OPENAI_API_KEY <your_openai_api_key>
  96. > azd env set AZURE_OPENAI_MODEL <your_openai_model>
  97. > ```
  98. > You can for example use the free [GitHub Models](https://docs.github.com/github-models/use-github-models/prototyping-with-ai-models#experimenting-with-ai-models-using-the-api) for this, or any other OpenAI compatible endpoint.
  99. ### Cost estimation
  100. Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage. However, you can use the Azure pricing calculator with pre-configured estimations to get an idea of the costs: [Azure Pricing Calculator](https://azure.com/e/0ddf5e6a4c654576a74b7199c85413b9).
  101. ### Clean up resources
  102. To clean up all the Azure resources created by this sample:
  103. ```bash
  104. azd down --purge
  105. ```
  106. ## Use Ollama for local development
  107. If you have a machine with enough resources, you can run this sample entirely locally without using any cloud resources. To do that, you first have to install [Ollama](https://ollama.com) and then run the following commands to download a model on your machine:
  108. ```bash
  109. ollama pull qwen3:8b
  110. ```
  111. > [!TIP]
  112. > If you have a powerful machine with enough memory, you can try using `gpt-oss:20b` instead to get better results.
  113. After that create a `.env` file in the root of the project with the following content:
  114. ```env
  115. AZURE_OPENAI_API_ENDPOINT="http://localhost:11434/v1"
  116. AZURE_OPENAI_MODEL="qwen3:8b"
  117. AZURE_OPENAI_API_KEY="__not_used__"
  118. ```
  119. You can now continue to the [run locally](#run-locally) section to start the application.
  120. > [!NOTE]
  121. > Local models may not work as well as cloud-hosted models, and may even fail to respond for some complex requests. This is a limitation of the local models and not of the application itself.
  122. ## Run locally
  123. After setting up your environment and either provisioned the Azure resources or set up Ollama, you can run the entire application locally:
  124. ```bash
  125. # Install dependencies for all services
  126. npm install
  127. # Start all services locally
  128. npm start
  129. ```
  130. Starting the different services may take some time, you need to wait until you see the following message in the terminal: `🚀 All services ready 🚀`
  131. This will start:
  132. - **Agent Web App**: http://localhost:4280
  133. - **Agent API**: http://localhost:7072
  134. - **Burger Web App**: http://localhost:5173
  135. - **Burger API**: http://localhost:7071
  136. - **Burger MCP Server**: http://localhost:3000
  137. > [!NOTE]
  138. > When running locally without having deployed the application, the servers will use in-memory storage, so any data will be lost when you stop the servers.
  139. > After a successful deployment, the servers will use Azure Cosmos DB for persistent storage.
  140. You can then open the Agent web app and ask things like:
  141. - _What spicy burgers do you have?_
  142. - _Order two Classic Cheeseburgers with extra bacon._
  143. - _Show my recent orders_
  144. The agent will decide which MCP tool(s) to call, then come up with a response.
  145. ### Available scripts
  146. This project uses [npm workspaces](https://docs.npmjs.com/cli/v9/using-npm/workspaces) to manage multiple packages in a single repository. You can run scripts from the root folder that will apply to all packages, or you can run scripts for individual packages as indicated in their respective README files.
  147. Common scripts (run from repo root):
  148. | Action | Command |
  149. | ---------------- | ------------------ |
  150. | Start everything | `npm start` |
  151. | Build all | `npm run build` |
  152. | Lint | `npm run lint` |
  153. | Fix lint | `npm run lint:fix` |
  154. | Format | `npm run format` |
  155. ## MCP tools
  156. The Burger MCP server provides these tools for AI agents:
  157. | Tool Name | Description |
  158. | ------------------------ | -------------------------------------------------------------------------------------------- |
  159. | `get_burgers` | Get a list of all burgers in the menu |
  160. | `get_burger_by_id` | Get a specific burger by its ID |
  161. | `get_toppings` | Get a list of all toppings in the menu |
  162. | `get_topping_by_id` | Get a specific topping by its ID |
  163. | `get_topping_categories` | Get a list of all topping categories |
  164. | `get_orders` | Get a list of all orders in the system |
  165. | `get_order_by_id` | Get a specific order by its ID |
  166. | `place_order` | Place a new order with burgers (requires `userId`, optional `nickname`) |
  167. | `delete_order_by_id` | Cancel an order if it has not yet been started (status must be `pending`, requires `userId`) |
  168. ### Testing the MCP Server
  169. #### Using the MCP Inspector
  170. You can test the MCP server using the MCP Inspector:
  171. 1. Install and start MCP Inspector:
  172. ```bash
  173. npx -y @modelcontextprotocol/inspector
  174. ```
  175. 2. In your browser, open the MCP Inspector (the URL will be shown in the terminal)
  176. 3. Configure the connection:
  177. - **Transport**: Streamable HTTP
  178. - **URL**: `http://localhost:3000/mcp`
  179. 4. Click **Connect** and explore the available tools
  180. #### Using GitHub Copilot
  181. To use the MCP server in local mode with GitHub Copilot, create a local `.vscode/mcp.json` configuration file in your project root:
  182. ```json
  183. {
  184. "servers": {
  185. "burger-mcp": {
  186. "type": "stdio",
  187. "command": "npm",
  188. "args": ["run", "start:local", "--workspace=burger-mcp"]
  189. }
  190. }
  191. }
  192. ```
  193. If you open that file
  194. Then, you can use GitHub Copilot in **agent mode** to interact with the MCP server. For example, you can ask questions like "What burgers are available?" or "Place an order for a vegan burger" and Copilot will use the MCP server to provide answers or perform actions.
  195. > [!TIP]
  196. > Copilot models can behave differently regarding tools usage, so if you don't see it calling the `burger-mcp` tools, you can explicitly mention using the Bruger MCP server by adding `#burger-mcp` in your prompt.
  197. ## Resources
  198. Here are some resources to learn more about the technologies used in this project:
  199. - [Model Context Protocol](https://modelcontextprotocol.io/) - More about the MCP protocol
  200. - [MCP for Beginners](https://github.com/microsoft/mcp-for-beginners) - A beginner-friendly introduction to MCP
  201. - [Generative AI with JavaScript](https://github.com/microsoft/generative-ai-with-javascript) - Learn how to build Generative AI applications with JavaScript
  202. - [Azure AI Travel Agents with Llamaindex.TS and MCP](https://github.com/Azure-Samples/azure-ai-travel-agents/) - Sample for building AI agents using Llamaindex.TS and MCP
  203. - [Serverless AI Chat with RAG using LangChain.js](https://github.com/Azure-Samples/serverless-chat-langchainjs) - Sample for building a serverless AI chat grounded on your own data with LangChain.js
  204. You can also find [more Azure AI samples here](https://github.com/Azure-Samples/azureai-samples).
  205. ## Troubleshooting
  206. If you encounter issues while running or deploying this sample:
  207. 1. **Dependencies**: Ensure all required tools are installed and up to date
  208. 2. **Ports**: Make sure required ports (3000, 4280, 5173, 5174, 7071, 7072) are not in use
  209. 3. **Azure Developer CLI**: Verify you're authenticated with `azd auth login`
  210. 4. **Node.js version**: Ensure you're using Node.js 22 or higher
  211. For more detailed troubleshooting, check the individual README files in each service directory.
  212. ## FAQ
  213. ### What is MCP (Model Context Protocol)?
  214. MCP is a protocol that enables AI agents to interact with external tools and APIs in a standardized way. It provides a common interface for tools, making it easier to integrate different services and capabilities into AI agents. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io/).
  215. ### How does this project differ from other AI agent samples?
  216. This sample focuses on **MCP integration** with LangChain.js in a **serverless architecture**. Unlike standalone agent examples, this project demonstrates:
  217. - Multi-service architecture (web UIs, APIs, MCP server)
  218. - Production-ready deployment on Azure
  219. - Real-world use case (burger ordering system)
  220. - Integration with popular AI tools (GitHub Copilot, Claude)
  221. ### Which LLM providers are supported?
  222. The agent supports any OpenAI-compatible endpoint:
  223. - **Azure OpenAI** (default when deployed to Azure)
  224. - **GitHub Models** (free alternative)
  225. - **Ollama** (local development)
  226. - Any other OpenAI-compatible API (set via `AZURE_OPENAI_API_ENDPOINT`)
  227. ### What's the difference between local and cloud deployment?
  228. **Local development:**
  229. - Uses in-memory storage (data lost on restart)
  230. - No cloud costs
  231. - Requires local setup (Node.js, Docker)
  232. - Perfect for testing and development
  233. **Azure deployment:**
  234. - Uses Azure Cosmos DB for persistent storage
  235. - Production-ready with authentication
  236. - Single-command deployment with `azd up`
  237. - Scalable and cost-effective serverless architecture
  238. ### How does the MCP server work?
  239. The Burger MCP server exposes burger API operations as MCP tools:
  240. - It translates API calls into MCP tool definitions
  241. - AI agents can discover and call these tools automatically
  242. - Uses Streamable HTTP transport for communication
  243. - Works with MCP-compatible clients (Copilot, Claude, etc.)
  244. ### Can I use this MCP server with other AI tools?
  245. Yes! The MCP server is compatible with:
  246. - **GitHub Copilot** (agent mode) - via `.vscode/mcp.json` config
  247. - **Claude Desktop** - via MCP client configuration
  248. - **MCP Inspector** - for testing and debugging
  249. - Any MCP-compatible client
  250. ### What are the prerequisites for deployment?
  251. - **Azure account** with `Microsoft.Authorization/roleAssignments/write` permissions
  252. - **Azure Developer CLI** (azd) 1.19+
  253. - **Node.js** 22+ LTS
  254. - **Git** for cloning the repository
  255. ### How do I customize the MCP tools?
  256. You can extend the MCP server by:
  257. 1. Adding new tool definitions in `packages/burger-mcp`
  258. 2. Implementing corresponding API endpoints in `packages/burger-api`
  259. 3. Updating the tool schema to expose new operations
  260. 4. Testing with MCP Inspector before deployment
  261. ### Why am I getting "model capacity" errors on Azure?
  262. If using Azure for Students or Free Trial, run:
  263. ```bash
  264. azd env set AZURE_OPENAI_MODEL_CAPACITY 1
  265. ```
  266. This ensures resources fit within free tier limits. You may also need to provide an alternative OpenAI endpoint.
  267. ### Where can I get help?
  268. - Join the [Microsoft Foundry Discord](https://aka.ms/foundry/discord)
  269. - Visit the [Developer Forum](https://aka.ms/foundry/forum)
  270. - Check the [MCP for Beginners](https://github.com/microsoft/mcp-for-beginners) guide
  271. ## Built for AI Agents
  272. This project has been optimized for use with AI agents like [GitHub Copilot](https://github.com/features/copilot). This includes:
  273. - Built-in context engineering provided with [AGENTS.md](https://agents.md/) files to help AI agents understand and extend the codebase.
  274. - [Reusable prompts](./.github/prompts/) for common tasks.
  275. - [Custom instructions](./.github/instructions/) tailored for each service of the project.
  276. - Custom **Codebase Explorer** chat mode for Copilot, to help you explore and understand the codebase.
  277. To learn how to set up and use GitHub Copilot with this repository, check out the [docs/copilot.md](./docs/copilot.md) guide.
  278. ## Getting Help
  279. If you get stuck or have any questions about building AI apps, join:
  280. [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord)
  281. If you have product feedback or errors while building visit:
  282. [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.