Repository files navigation

This is a quick start guide that provides the basic building blocks to set up a remote Model Context Protocol (MCP) server using Azure Container Apps. The MCP server is built using Node.js and TypeScript, and it can be used to run various tools and services in a serverless environment. This project also implements a multi-layered security architecture combining JWT-based authentication with role-based access control (RBAC) to secure the MCP server endpoints and tools.

The Model Context Protocol (MCP) is an open protocol that allows Large Language Models (LLMs) to interact with external tools and services in a standardized way. MCP enables LLMs to access and utilize various resources, such as databases, APIs, and other services, to enhance their capabilities and provide more accurate and relevant responses.

Below is the architecture diagram for a typical MCP server setup:

flowchart TD    user(("fa:fa-users User"))    host["VS Code, Copilot, LlamaIndex, Langchain..."]    clientHttp[MCP HTTP Client]    serverHttp([MCP HTTP Server])    agent["Agents (not included in this demo)"]    AzureOpenAI([Azure AI Foundry])    GitHub([GitHub Models])    OpenAI([OpenAI])        tools["fa:fa-wrench Tools"]    db[(sqlite DB)]    user --> hostGroup     subgraph hostGroup["MCP Host"]        host -.- agent        host aaa@ -.- clientHttp    end        agent -.- AzureOpenAI & GitHub & OpenAI        clientHttp aa@ ---> |"Streamable HTTP (authenticated)"| serverHttp    subgraph container["ACA or localhost"]      serverHttp a@ -.- tools      tools b@ -.- add_todo       tools c@ -.- list_todos      tools d@ -.- complete_todo      tools e@ -.- delete_todo    end    add_todo bb@ --> db    list_todos cc@--> db    complete_todo dd@ --> db    delete_todo ee@ --> db    %% styles    classDef animate stroke-dasharray: 9,5,stroke-dashoffset: 900,animation: dash 25s linear infinite;    classDef highlight fill:#9B77E8,color:#fff,stroke:#5EB4D8,stroke-width:2px        class a animate    class aa animate    class aaa animate    class b animate    class c animate    class d animate    class e animate    class bb animate    class cc animate    class dd animate    class ee animate    class container highlight

Azure Container Apps is a fully managed, serverless container platform that simplifies the deployment and operation of containerized applications. ACA also provides serverless GPU support, so that you can bring your own containers and deploy them to GPU-backed environments that automatically scale based on demand.

Key benefits:

• Autoscaling – scale to zero when idle, scale out with usage
• Pay-per-second billing – pay only for the compute you use
• Ease of use - accelerate developer velocity and easily bring any container and run it on GPUs in the cloud
• No infrastructure management – focus on your model and app
• Enterprise-grade features – out of the box support for bringing your own virtual networks, managed identity, private endpoints and more with full data governance

1. Install the latest version ofVS Code
2. InstallGitHub Copilot andGitHub Copilot Chat extensions

If you prefer to run the MCP server locally, you can do so by following these steps.

You need to have the following tools installed on your local machine:

• git necessary to clone the repository.
• Node.js and npm.

Once you have the prerequisites installed, you can follow these steps to run the MCP server locally:

1. Clone this repository:

git clone https://github.com/Azure-Samples/mcp-container-tscd mcp-container-ts

2. Install project dependencies

npm install

3. Generate a new JWT configuration:

npm run generate-token -- --admin

This will append (or create) a new JWT configuration to.env file at the root of the project. The generated token will be used to authenticate requests to the MCP server.

4. Start the dev server

npm run dev

You should see the following output in the terminal:

  mcp:db 2025-07-23T16:48:05.381Z PRAGMA journal_mode = WAL +0ms  mcp:db 2025-07-23T16:48:05.382Z CREATE TABLE IF NOT EXISTS todos (  mcp:db      id INTEGER PRIMARY KEY AUTOINCREMENT,  mcp:db      text TEXT NOT NULL,  mcp:db      completed INTEGER NOT NULL DEFAULT 0  mcp:db    ) +0ms  mcp:db 2025-07-23T16:48:05.382Z Database"todos" initialized. +0ms  mcp:index 2025-07-23T16:48:05.449Z MCP Stateless Streamable HTTP Server +0ms  mcp:index 2025-07-23T16:48:05.449Z MCP endpoint: http://localhost:3000/mcp +0ms  mcp:index 2025-07-23T16:48:05.449Z Press Ctrl+C to stop the server +0ms

4. To access and use the MCP server, read theUse your MCP server section below.

To deploy the MCP server to Azure Container Apps, you can use the Azure Developer CLI (azd). This will allow you to provision and deploy the project to Azure with minimal effort:

• Install theAzure Developer CLI.

Once you have the prerequisites installed, you can follow these steps to deploy the MCP server to Azure Container Apps:

1. Clone this repository

git clone https://github.com/azure-samples/mcp-container-ts.gitcd mcp-container-ts

2. Log in to your Azure account

azd auth login

For GitHub Codespaces users, if the previous command fails, try:

azd auth login --use-device-code

1. Provision and deploy the project (ensure you are in the folder of the cloned repo when running this command):

azd up

4. Once the deployment is complete, you can access the MCP server using the URL provided in the output. The URL will look something like this:

https://<env-name>.<container-id>.<region>.azurecontainerapps.io

5. To access and use the MCP server, read theUse your MCP server section below.

azd down --purge --force

You have a few other options to get started with this template. The quickest way to get started is GitHub Codespaces, since it will setup all the tools for you and you can run the MCP server in the browser.

You can run this template virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:

1. Open the template (this may take several minutes):

   

2. Open a terminal window

3. Continue with the next steps to either run the MCP server locally or deploy it to Azure Container Apps.

A related option is VS Code Dev Containers, which will open the project in your local VS Code using theDev Containers extension:

1. InstallDocker Desktop andVS Code Dev Containers extension if not already installed.

2. Start Docker Desktop (install it if not already installed)

3. Open the project:

   

4. Open a terminal window

5. Continue with the next steps to either run the MCP server locally or deploy it to Azure Container Apps.

This repository contains an example that demonstrates how to use the MCP server with OpenAI models. The example is located in the[examples/](./examples/) directory.

The quickest way to connect to the MCP server is the use the provided.vscode/mcp.json configuration file to set up the MCP server in your VS Code environment. This configuration file contains the necessary settings for the MCP server, including the URL and transport type.

{"inputs": [    {"password":true,"id":"mcp-server-token","description":"Enter the token for the MCP server","type":"promptString",    }  ],"servers": {"mcp-server": {"type":"http","url":"http://localhost:3000/mcp","headers": {"Authorization":"Bearer ${input:mcp-server-token}"      }    },"mcp-server-remote": {"type":"http","url":"https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp","headers": {"Authorization":"Bearer ${input:mcp-server-token}"      }    }  }}

Once you have this file opened, you can click on the "start" inlined action button that will connect the MCP server and fetch the available tools.

IMPORTANT: Because the server is secured with a JWT token, you will be prompted by VS Code to enter the token. You need to copy the value of the"JWT_TOKEN" from the.env file created by thenpm run generate-token command.

1. Add MCP Server from command palette and add URL to your running server's HTTP endpoint:

For local development, the URL will be:

http://localhost:3000/mcp

For Azure Container Apps, the URL will be:

https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp

1. SelectHTTP (HTTP or Server-Sent Events) for the type of MCP server to add.
2. Enter the URL to your running HTTP endpoint, including the/mcp path at the end.
3. Enter the server ID. (This can be any name you want)
4. Choose if you want to run this in your User settings (available to all apps for you) or to your Workspace settings (available to this app, only)
5. In Copilot chat agent mode enter a prompt to trigger the tool, e.g., select some code and enter this prompt

I need to send an email to Dan, please add that to my todo list.

7. When prompted to run the tool, consent by clicking Continue,
8. When you're done, press Ctrl+C in the terminal window to stop the func.exe host process, and List MCP Servers from command palette and stop the local server.

1. In a new terminal window, install and runMCP Inspector

npm run inspect

1. CTRL click to load the MCP Inspector web app from the URL displayed in the terminal (e.g.http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xyz)
2. Set the transport type toStreamable HTTP.
3. Add authentication header:Authorization and Bearer token which is the value of the"JWT_TOKEN" from the.env file created by thenpm run generate-token command.
4. Set the URL to your running server's HTTP endpoint and Connect:

# for local development, use:http://localhost:3000/mcp# or use the Azure Container Apps URL:https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp

5. List Tools. Click on a tool and Run Tool.

• Learn more aboutModel Context Protocol
• Learn more aboutAzure Container Apps
• Learn more aboutAzure AI Foundry
• Learn more aboutrelated MCP efforts from Microsoft

We encourage you to join our Azure AI Foundry Developer Community​ to share your experiences, ask questions, and get support:

• aka.ms/foundry/discord​ - Join our Discord community for real-time discussions and support.
• aka.ms/foundry/forum - Visit our Azure AI Foundry Developer Forum to ask questions and share your knowledge.