Repository files navigation

A demonstration project showcasing Model Context Protocol (MCP) implementations using FastMCP, with examples of stdio and HTTP transports, integration with LangChain and Agent Framework, and deployment to Azure Container Apps.

• Getting started
  • GitHub Codespaces
  • VS Code Dev Containers
  • Local environment
• Run local MCP servers
  • Use with GitHub Copilot
  • Debug with VS Code
  • Inspect with MCP inspector
  • View traces with Aspire Dashboard
• Run local Agents <-> MCP
• Deploy to Azure
• Deploy to Azure with private networking
• Deploy to Azure with Keycloak authentication
• Deploy to Azure with Entra OAuth Proxy

You have a few options for setting up this project. The quickest way to get started is GitHub Codespaces, since it will setup all the tools for you, but you can also set it up locally.

You can run this project virtually by using GitHub Codespaces. Click the button to open a web-based VS Code instance in your browser:

Once the Codespace is open, open a terminal window and continue with the deployment steps.

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

1. Start Docker Desktop (install it if not already installed)
2. Open the project:
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
4. Continue with the deployment steps.

If you're not using one of the above options, then you'll need to:

1. Make sure the following tools are installed:

   • Azure Developer CLI (azd)
   • Python 3.13+
   • Docker Desktop
   • Git

2. Clone the repository and open the project folder.

3. Create aPython virtual environment and activate it.

4. Install the dependencies:

   uv sync

5. Copy.env-sample to.env and configure your environment variables:

   cp .env-sample .env

6. Edit.env with your API credentials. Choose one of the following providers by settingAPI_HOST:

   • github - GitHub Models (requiresGITHUB_TOKEN)
   • azure - Azure OpenAI (requires Azure credentials)
   • ollama - Local Ollama instance
   • openai - OpenAI API (requiresOPENAI_API_KEY)

This project includes MCP servers in theservers/ directory:

The local servers (basic_mcp_stdio.py andbasic_mcp_http.py) implement an "Expenses Tracker" with a tool to add expenses to a CSV file.

The.vscode/mcp.json file configures MCP servers for GitHub Copilot integration:

Available Servers:

• expenses-mcp: stdio transport server for production use
• expenses-mcp-debug: stdio server with debugpy on port 5678
• expenses-mcp-http: HTTP transport server athttp://localhost:8000/mcp. You must start this server manually withuv run servers/basic_mcp_http.py before using it.

Switching Servers:

Configure which server GitHub Copilot uses by opening the Chat panel, selecting the tools icon, and choosing the desired MCP server from the list.

Example input:

Use a query like this to test the expenses MCP server:

Log expense for 50 bucks of pizza on my amex today

The.vscode/launch.json provides a debug configuration to attach to an MCP server.

To debug an MCP server with GitHub Copilot Chat:

1. Set breakpoints in the MCP server code inservers/basic_mcp_stdio.py
2. Start the debug server viamcp.json configuration by selectingexpenses-mcp-debug
3. PressCmd+Shift+D to open Run and Debug
4. Select "Attach to MCP Server (stdio)" configuration
5. PressF5 or the play button to start the debugger
6. Select the "expenses-mcp-debug" server in GitHub Copilot Chat tools
7. Use GitHub Copilot Chat to trigger the MCP tools
8. Debugger pauses at breakpoints

TheMCP Inspector is a developer tool for testing and debugging MCP servers.

Note: While HTTP servers can technically work with port forwarding in Codespaces/Dev Containers, the setup for MCP Inspector and debugger attachment is not straightforward. For the best development experience with full debugging capabilities, we recommend running this project locally.

For stdio servers:

npx @modelcontextprotocol/inspector uv run servers/basic_mcp_stdio.py

For HTTP servers:

1. Start the HTTP server:

   uv run servers/basic_mcp_http.py

2. In another terminal, run the inspector:

   npx @modelcontextprotocol/inspector http://localhost:8000/mcp

The inspector provides a web interface to:

• View available tools, resources, and prompts
• Test tool invocations with custom parameters
• Inspect server responses and errors
• Debug server communication

You can use the.NET Aspire Dashboard to view OpenTelemetry traces, metrics, and logs from the MCP server.

Note: Aspire Dashboard integration is only configured for the HTTP server (basic_mcp_http.py).

1. Start the Aspire Dashboard:

   docker run --rm -d -p 18888:18888 -p 4317:18889 --name aspire-dashboard \    mcr.microsoft.com/dotnet/aspire-dashboard:latest

   The Aspire Dashboard exposes its OTLP endpoint on container port 18889. The mapping-p 4317:18889 makes it available on the host's standard OTLP port 4317.

   Get the dashboard URL and login token from the container logs:

   docker logs aspire-dashboard2>&1| grep"Login to the dashboard"

2. Enable OpenTelemetry by adding this to your.env file:

   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

3. Start the HTTP server:

   uv run servers/basic_mcp_http.py

4. View the dashboard at:http://localhost:18888

This project includes example agents in theagents/ directory that demonstrate how to connect AI agents to MCP servers:

To run an agent:

1. First start the HTTP MCP server:

   uv run servers/basic_mcp_http.py

2. In another terminal, run an agent:

   uv run agents/agentframework_http.py

The agents will connect to the MCP server and allow you to interact with the expense tracking tools through a chat interface.

This project can be deployed to Azure Container Apps using the Azure Developer CLI (azd). The deployment provisions:

• Azure Container Apps - Hosts both the MCP server and agent
• Azure OpenAI - Provides the LLM for the agent
• Azure Cosmos DB - Stores expenses data
• Azure Container Registry - Stores container images
• Log Analytics - Monitoring and diagnostics

1. Sign up for afree Azure account and create an Azure Subscription.
2. Check that you have the necessary permissions:
   • Your Azure account must haveMicrosoft.Authorization/roleAssignments/write permissions, such asRole Based Access Control Administrator,User Access Administrator, orOwner.
   • Your Azure account also needsMicrosoft.Resources/deployments/write permissions on the subscription level.

1. Login to Azure:

   azd auth login

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

   azd auth login --use-device-code

2. Create a new azd environment:

   azd env new

   This will create a folder inside.azure with the name of your environment.

3. Provision and deploy the resources:

   azd up

   It will prompt you to select a subscription and location. This will take several minutes to complete.

4. Once deployment is complete, a.env file will be created with the necessary environment variables to run the agents locally against the deployed resources.

Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.

You can try theAzure pricing calculator for the resources:

• Azure OpenAI Service: S0 tier, GPT-4o-mini model. Pricing is based on token count.Pricing
• Azure Container Apps: Consumption tier.Pricing
• Azure Container Registry: Standard tier.Pricing
• Azure Cosmos DB: Serverless tier.Pricing
• Log Analytics (Optional): Pay-as-you-go tier. Costs based on data ingested.Pricing

⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use, either by deleting the resource group in the Portal or runningazd down.

The URL of the deployed MCP server is available in the azd environment variableMCP_SERVER_URL, and is written to the.env file created after deployment.

1. To avoid conflicts, stop the MCP servers frommcp.json and disable the expense MCP servers in GitHub Copilot Chat tools.

2. Select "MCP: Add Server" from the VS Code Command Palette

3. Select "HTTP" as the server type

4. Enter the URL of the MCP server, based on theMCP_SERVER_URL environment variable.

5. Enable the MCP server in GitHub Copilot Chat tools and test it with an expense tracking query:

   Log expense for 75 dollars of office supplies on my visa last Friday

After deployment sets up the required Azure resources (Cosmos DB, Application Insights), you can also run the MCP server locally against those resources:

# Run the MCP servercd servers&& uvicorn deployed_mcp:app --host 0.0.0.0 --port 8000

By default, OpenTelemetry tracing is enabled for the deployed MCP server, sending traces to Azure Application Insights. To bring up a dashboard of metrics and traces, run:

azd monitor

Or you can use Application Insights directly:

1. Open the Azure Portal and navigate to the Application Insights resource created during deployment (named<project-name>-appinsights).
2. In Application Insights, go to "Transaction Search" to view traces from the MCP server.
3. You can filter and analyze traces to monitor performance and diagnose issues.

You can also view OpenTelemetry traces inLogfire by configuring the MCP server to send traces there.

1. Create a Logfire account and get your write token from the Logfire dashboard.

2. Set the azd environment variables to enable Logfire:

   azd envset OPENTELEMETRY_PLATFORM logfireazd envset LOGFIRE_TOKEN<your-logfire-write-token>

3. Provision and deploy:

   azd up

4. Open the Logfire dashboard to view traces from the MCP server.

To demonstrate enhanced security for production deployments, this project supports deploying with a virtual network (VNet) configuration that restricts public access to Azure resources.

1. Set these azd environment variables to set up a virtual network and private endpoints for the Container App, Cosmos DB, and OpenAI resources:

   azd envset USE_VNETtrueazd envset USE_PRIVATE_INGRESStrue

   The Log Analytics and ACR resources will still have public access enabled, so that you can deploy and monitor the app without needing a VPN. In production, you would typically restrict these as well.

2. Provision and deploy:

   azd up

When using VNet configuration, additional Azure resources are provisioned:

• Virtual Network: Pay-as-you-go tier. Costs based on data processed.Pricing
• Azure Private DNS Resolver: Pricing per month, endpoints, and zones.Pricing
• Azure Private Endpoints: Pricing per hour per endpoint.Pricing

This project supports deploying with OAuth 2.0 authentication using Keycloak as the identity provider, implementing theMCP OAuth specification with Dynamic Client Registration (DCR).

1. Enable Keycloak authentication:

   azd envset MCP_AUTH_PROVIDER keycloak

2. Set the Keycloak admin password (required):

   azd envset KEYCLOAK_ADMIN_PASSWORD"YourSecurePassword123!"

3. Optionally customize the realm name (default:mcp):

   azd envset KEYCLOAK_REALM_NAME"mcp"

4. Deploy to Azure:

   azd up

   This will create the Azure Container Apps environment, deploy Keycloak with the pre-configured realm, deploy the MCP server with OAuth validation, and configure HTTP route-based routing.

5. Verify deployment by checking the outputs:

   azd env get-value MCP_SERVER_URLazd env get-value KEYCLOAK_DIRECT_URLazd env get-value KEYCLOAK_ADMIN_CONSOLE

6. Visit the Keycloak admin console to verify the realm is configured:

   https://<your-mcproutes-url>/auth/admin

   Login withadmin and your configured password.

The Keycloak deployment supports Dynamic Client Registration (DCR), which allows VS Code to automatically register as an OAuth client. VS Code redirect URIs are pre-configured in the Keycloak realm.

To use the deployed MCP server with GitHub Copilot Chat:

1. To avoid conflicts, stop the MCP servers frommcp.json and disable the expense MCP servers in GitHub Copilot Chat tools.

2. Select "MCP: Add Server" from the VS Code Command Palette

3. Select "HTTP" as the server type

4. Enter the URL of the MCP server fromazd env get-value MCP_SERVER_URL

5. You should see a Keycloak authentication screen open in your browser. Select "Allow access":

   

6. Sign in with a Keycloak user (e.g.,testuser /testpass for the pre-configured demo user):

   

7. After authentication, the browser will redirect back to VS Code:

   

8. Enable the MCP server in GitHub Copilot Chat tools:

   

9. Test it with an expense tracking query:

   Log expense for 75 dollars of office supplies on my visa last Friday

   

10. Verify the expense was added by checking the Cosmos DBuser-expenses container in the Azure Portal or by asking GitHub Copilot Chat:

    Show me my expenses from last week

Note: Keycloak must be publicly accessible because its URL is dynamically generated by Azure. Token issuer validation requires a known URL, but the mcproutes URL isn't available until after deployment. Using a custom domain would fix this.

This project supports deploying with Microsoft Entra ID (Azure AD) authentication using FastMCP's built-in Azure OAuth proxy. This is an alternative to Keycloak that uses Microsoft Entra with your Azure tenant for identity management.

1. Enable Entra OAuth proxy:

   azd envset MCP_AUTH_PROVIDER entra_proxy

2. Set your tenant ID so that the App Registration is created in the correct tenant:

   azd envset AZURE_TENANT_ID"<your-tenant-id>"

3. Deploy to Azure:

   azd up

   During deployment:

   • Preprovision hook: Creates a Microsoft Entra App Registration with a client secret, and stores the credentials in azd environment variables
   • Postprovision hook: Updates the App Registration with the deployed server URL as an additional redirect URI

4. Verify deployment by checking the outputs:

   azd env get-value MCP_SERVER_URLazd env get-value ENTRA_PROXY_AZURE_CLIENT_ID

The following environment variables are automatically set by the deployment hooks:

These are then written to.env by the postprovision hook for local development.

After deployment, you can test locally with OAuth enabled:

# Run the MCP servercd servers&& uvicorn auth_mcp:app --host 0.0.0.0 --port 8000

The server will use the Entra App Registration for OAuth and CosmosDB for client storage.

The Entra App Registration includes these redirect URIs for VS Code:

• https://vscode.dev/redirect (VS Code web)
• http://127.0.0.1:{33418-33427} (VS Code desktop local auth helper, 10 ports)

To use the deployed MCP server with GitHub Copilot Chat:

1. To avoid conflicts, stop the MCP servers frommcp.json and disable the expense MCP servers in GitHub Copilot Chat tools.

2. Select "MCP: Add Server" from the VS Code Command Palette

3. Select "HTTP" as the server type

4. Enter the URL of the MCP server, either fromMCP_SERVER_URL environment variable orhttp://localhost:8000/mcp if running locally.

5. If you get an error about "Client ID not found", open the Command Palette, run"Authentication: Remove Dynamic Authentication Providers", and select the MCP server URL. This clears any cached OAuth tokens and forces a fresh authentication flow. Then restart the server to prompt the OAuth flow again.

6. You should see a FastMCP authentication screen open in your browser. Select "Allow access":

   

7. After granting access, the browser will redirect to a VS Code "Sign-in successful!" page and then bring focus back to VS Code.

   

8. Enable the MCP server in GitHub Copilot Chat tools and test it with an expense tracking query:

   Log expense for 75 dollars of office supplies on my visa last Friday

   

9. Verify the expense was added by checking the Cosmos DBuser-expenses container in the Azure Portal.