Table of Contents

  1. Introduction
  2. Prerequisites
  3. Setting Up Azure Foundry AI Agent
  4. Creating Your First Agent
  5. Configuring MCP Server Connection
  6. Testing and Validation
  7. Troubleshooting
  8. Next Steps

Introduction

This guide provides complete, step-by-step instructions for connecting to Model Context Protocol (MCP) servers from Azure Foundry AI Agent without writing any code. Azure Foundry AI Agent allows you to create intelligent agents that leverage MCP tools through simple YAML configuration, making it accessible to users of all technical levels.

What You’ll Build

By the end of this guide, you’ll have:

  • An Azure Foundry AI Agent connected to a remote MCP server
  • The ability to use MCP tools (like getting time in different timezones) through natural language
  • A working agent that can orchestrate complex workflows using MCP tools
  • Knowledge of how to configure additional MCP servers

Architecture Overview

┌ │ │ └ ─ ─ ─ ─ ─ ─ ─ U ( ─ ─ s N ─ ─ e a ─ ─ r t ─ ─ u ─ ─ r ─ ─ a ─ ─ l ─ ─ ─ ─ L ─ ─ a ─ ─ n ─ ─ g ─ ─ u ─ ─ a ─ ─ g ─ ─ e ─ ─ ) ─ ┐ │ │ ┘ ─ ─ ─ ─ ─ ─ ─ ─ ▶ ┌ │ │ └ ─ ─ ┌ │ │ └ ┌ │ │ │ │ └ ─ ─ ─ ─ ─ ─ ─ A ( ─ ─ ─ ─ - - - ─ ─ z V ─ ─ ─ ─ ─ ─ u i ─ ─ M ( ─ ─ M g g [ ─ ─ r s ─ ─ C R ─ ─ C e e O ─ ─ e u ─ ─ P e ─ ─ P t t t ─ ─ a ─ ─ m ─ ─ _ _ h ─ ─ F l ─ ─ S o ─ ─ T c c e ─ ─ o ─ ─ e t ─ ─ o u u r ─ ─ u D ─ │ ▼ ─ r e ─ │ ▼ ─ o r r ─ ─ n e ─ ─ v / ─ ─ l r r t ─ ─ d s ─ ─ e A ─ ─ s e e o ─ ─ r i ─ ─ r z ─ ─ n n o ─ ─ y g ─ ─ u ─ ─ t t l ─ ─ n ─ ─ r ─ ─ _ _ s ─ ─ A e ─ ─ e ─ ─ u t ] ─ ─ I r ─ ─ ) ─ ─ t i ─ ─ ─ ─ ─ ─ c m ─ ─ A + ─ ─ ─ ─ _ e ─ ─ g ─ ─ ─ ─ t _ ─ ─ e Y ─ ─ ─ ─ i f ─ ─ n A ─ ─ ─ ─ m o ─ ─ t M ─ ┐ │ │ ┘ ┐ │ e r │ ┘ ─ L ─ _ ─ ─ t ─ C ─ i ─ o ─ m ─ n ─ e ─ f ─ z ─ i ─ o ─ g ─ n ─ ) ─ e ─ ─ ┐ │ │ ┘

Why No Code?

Azure Foundry AI Agent is a codeless/low-code solution that uses:

  • Visual Designer: Drag-and-drop interface for agent configuration
  • YAML Configuration: Simple text-based configuration for advanced settings
  • Pre-built Tool Types: Including MCP, OpenAPI, Bing Search, Code Interpreter, and more
  • Managed Orchestration: Azure handles all the complex LLM-to-tool communication

Prerequisites

Before you begin, ensure you have:

Azure Environment

  1. Azure Subscription

    • An active Azure subscription
    • Access to create Azure AI Foundry resources

  2. Azure AI Foundry Hub

  3. VS Code with Azure AI Foundry Extension

    • Visual Studio Code installed
    • Azure AI Foundry for VS Code extension (search for “Azure AI Foundry” in extensions)
    • Sign in with your Azure account

MCP Server Access

  • MCP Server URL: A publicly accessible MCP server endpoint
  • For this tutorial, we use the MCP server described in Building MCP Server with ASP.NET Core
  • The server should have an SSE endpoint available (typically /sse)

Knowledge Requirements

  • Basic understanding of Azure cloud concepts
  • Familiarity with natural language prompts
  • No coding knowledge required!

Setting Up Azure Foundry AI Agent

Step 1: Install VS Code Extension

  1. Open Visual Studio Code
  2. Click on the Extensions icon in the left sidebar (or press Ctrl+Shift+X)
  3. Search for “Azure AI Foundry”
  4. Click Install on the official Microsoft extension

Step 2: Sign In to Azure

  1. Click on the Azure icon in the left sidebar (cloud icon)
  2. Click Sign in to Azure
  3. Follow the browser authentication flow
  4. Return to VS Code once authentication completes

Step 3: Set Default Project

  1. In the VS Code command palette (Ctrl+Shift+P), type: “Azure AI Foundry: Set Default Project”
  2. Select your Azure subscription
  3. Select your Azure AI Foundry hub
  4. Select your project

You’ll see the Azure AI Foundry Explorer panel in the left sidebar showing:

  • Your hub name
  • Agents section
  • Connected resources

Creating Your First Agent

Step 1: Create New Agent

  1. In the Azure AI Foundry Explorer panel (left sidebar):

    • Locate the Agents section
    • Click the "+" icon next to “Agents”

  2. A new agent configuration window opens with:

    • YAML configuration on the left side
    • Visual designer on the right side

Step 2: Configure Basic Agent Settings

In the visual designer panel, fill in these fields:

  1. Agent Name (required):

    m y - m c p - t i m e - a g e n t

  2. Model (required):

    • Click the model dropdown
    • Select your deployed model (e.g., gpt-4, gpt-35-turbo)

  3. Description:

    A n a g e n t t h a t c a n t e l l y o u t h e c u r r e n t t i m e i n a n y t i m e z o n e u s i n g M C P t o o l s

  4. Instructions:

    Y W u A o h s l u e e w n a a t y r u h s e s e e r a r a e s v s h a p e a i o l s l n p k a d f b u a l w l b e i o t a u M h s t C s P t i t h s h t e t e o a o t n c l i t u s m r e w r t z i e o o t n n h t p e r a t o u c i v s c m i e e e d d s e s i f n a o t c r o s c p u c t e r l o c a a o i t r l f e i s i , t c y f r . o l e r o a c l g a - e t t t i i t o m i n e n s g i o n t r f i o m t r e i m m a i e t n z i f o o o n n r e . m s a , t i o n .

Step 3: Save Initial Configuration

  1. Press Ctrl+S (or use File → Save)
  2. The YAML configuration is automatically saved

Step 4: Review Generated YAML

Your YAML configuration should look like this:

name: my-mcp-time-agent
model:
  deployment: gpt-4
  parameters:
    temperature: 0.7
    top_p: 1
description: An agent that can tell you the current time in any timezone using MCP tools
instructions: |
  You are a helpful assistant with access to tools for getting time information.
  When users ask about the current time in specific locations or timezones,
  use the available MCP tools to provide accurate, real-time information.
  Always respond with the timezone used for clarity.
tools: []

Configuring MCP Server Connection

Important Note: Manual YAML Configuration Required

Unfortunately, the Azure Foundry visual designer and VS Code extension’s UI currently cannot automatically discover tools from MCP servers. This is a known limitation. However, you can configure MCP servers manually by editing the YAML.

The following steps describe the solution developed during this tutorial:

Step 1: Edit the Agent YAML Configuration

The agent’s YAML file is already open in your editor. Look for the tools: section (currently empty []).

Step 2: Add MCP Server Configuration

Replace the empty tools: [] line with the following MCP server configuration:

tools:
  - type: mcp
    id: get_time
    options:
      server_url: https://your-mcp-server-url/sse

Important: Replace https://your-mcp-server-url/sse with your actual MCP server URL.

Step 3: Optional - Specify Allowed Tools

You can optionally restrict which tools the agent can access by adding allowed_tools:

tools:
  - type: mcp
    id: get_time
    options:
      server_url: https://your-mcp-server-url/sse
      allowed_tools:
        - get_current_utc_time
        - get_current_time_for_timezone

Step 4: Save Configuration

  1. Press Ctrl+S (or File → Save)
  2. The configuration is saved locally

Complete Example YAML

Here’s a complete agent configuration with MCP tools:

name: my-mcp-time-agent
model:
  deployment: gpt-4
  parameters:
    temperature: 0.7
    top_p: 1
description: An agent that can tell you the current time in any timezone using MCP tools
instructions: |
  You are a helpful assistant with access to tools for getting time information.
  When users ask about the current time in specific locations or timezones,
  use the available MCP tools to provide accurate, real-time information.
  Always respond with the timezone used for clarity.
tools:
  - type: mcp
    id: get_time
    options:
      server_url: https://your-mcp-server-url/sse
      allowed_tools:
        - get_current_utc_time
        - get_current_time_for_timezone

Understanding the MCP Configuration

Let’s break down each part of the MCP configuration:

Field Purpose Example
type: mcp Identifies this as an MCP tool integration Always mcp
id: get_time Unique identifier for this MCP server instance Use descriptive names like get_time, weather_tools, etc.
server_url The HTTPS endpoint of your MCP server https://your-domain.azurewebsites.net/sse
allowed_tools (Optional) List of tools the agent can use get_current_utc_time, get_current_time_for_timezone

Step 5: Deploy Agent to Azure

Once your YAML is configured with the MCP server:

  1. Look for the “Create Agent on Azure AI Foundry” button in VS Code
  2. Click it to deploy your agent to Azure
  3. Wait for the deployment to complete
  4. You’ll see a notification when the agent is ready

Testing and Validation

Step 1: Access Agent in Azure AI Foundry Portal

  1. Open the Azure AI Foundry portal
  2. Navigate to your project
  3. Find your agent in the Agents section
  4. Click to open the agent details page

Step 2: Test Using Agent Playground

  1. In the agent details page, find the Playground or Test tab
  2. You should see a chat interface

Step 3: Test Simple Queries (No Tools)

Try these messages to verify the agent works:

Test 1: Simple greeting

H e l l o ! H o w a r e y o u ?

Expected Response: The agent responds with a friendly greeting. No tools should be called.

Step 4: Test Tool Execution

Try these messages to trigger MCP tool calls:

Test 2: Get current UTC time

W h a t i s t h e c u r r e n t t i m e i n U T C ?

Expected Response:

T h e c u r r e n t t i m e i n U T C i s [ t i m e f r o m M C P t o o l ]

The agent should:

  1. Recognize you’re asking for time
  2. Call the get_current_utc_time MCP tool
  3. Return the result with the timezone clarified

Test 3: Get time in specific timezone

W h a t i s t h e c u r r e n t t i m e i n N e w Y o r k ?

Expected Response:

T h e c u r r e n t t i m e i n N e w Y o r k ( A m e r i c a / N e w _ Y o r k t i m e z o n e ) i s [ t i m e f r o m M C P t o o l ]

Test 4: Multiple timezone queries

C a n y o u t e l l m e t h e c u r r e n t t i m e i n L o n d o n , T o k y o , a n d S y d n e y ?

Expected Response: The agent should call the MCP tool multiple times and provide times for all three locations.

Troubleshooting

Common Issues and Solutions

Issue 1: “Agent Cannot Find MCP Server”

Symptoms:

  • Tool calls fail with “MCP server not found” errors
  • Agent responds that tools are unavailable

Solutions:

  1. Verify MCP Server URL:

    • Ensure the URL in server_url is correct
    • Test the URL in a browser or with curl: 
      curl -i https://your-mcp-server-url/sse
    • You should get a 200 status code

  2. Check Server Accessibility:

    • Ensure the MCP server is publicly accessible (no VPN/firewall blocking)
    • Verify HTTPS is working (not just HTTP)
    • Test from a different network if possible

  3. Review Configuration:

    • Make sure the YAML format is correct
    • Verify there are no typos in the server_url
    • Ensure proper indentation in the YAML

  4. Redeploy Agent:

    • After fixing the URL, save the YAML
    • Click “Update Agent on Azure AI Foundry” to redeploy
    • Wait for deployment to complete

Issue 2: “Tool Execution Times Out”

Symptoms:

  • Tool calls take a very long time
  • Agent eventually responds with timeout error

Solutions:

  1. Check MCP Server Performance:

    • Test the MCP server directly: 
      time curl -i https://your-mcp-server-url/sse
    • A healthy server should respond within 5 seconds

  2. Check Network Connectivity:

    • Ensure no network issues between Azure and your MCP server
    • If server is on-premise, consider hosting it on Azure (Container Apps, App Service)

  3. Increase Timeout (if configurable):

    • Some agent configurations allow timeout adjustments
    • Check Azure AI Foundry documentation for timeout settings

Issue 3: “Tool Name Not Found” or “Unknown Tool”

Symptoms:

  • Agent doesn’t recognize available tools
  • Error messages about undefined tools

Solutions:

  1. Verify Tool Names:

    • Check the MCP server documentation for exact tool names
    • Common tool names for the example server:
      • get_current_utc_time
      • get_current_time_for_timezone
    • Tool names are case-sensitive!

  2. Update allowed_tools List:

    • If using allowed_tools, ensure names match exactly: 
      allowed_tools:
  - get_current_utc_time
  - get_current_time_for_timezone

  3. Remove allowed_tools (if unsure):

    • Remove the allowed_tools section to allow all tools: 
      tools:
  - type: mcp
    id: get_time
    options:
      server_url: https://your-mcp-server-url/sse

Issue 4: “MCP Server Returns Error”

Symptoms:

  • Tool calls execute but return errors
  • Error messages about invalid parameters

Solutions:

  1. Check Tool Arguments:

    • For timezone tool, ensure valid IANA timezone identifiers:
      V I a n l v i a d l : i d A : m e E r S i T c , a / P N S e T w , _ Y G o M r T k , ( t E h u e r s o e p e a / r L e o n a d b o b n r , e v A i s a i t a i / o T n o s k , y o n o t I A N A i d e n t i f i e r s )

  2. Test Tool Directly:

    • If possible, test the MCP tool directly using the server’s test interface
    • Review the MCP server’s documentation for parameter requirements

  3. Check Agent Instructions:

    • Your agent’s instructions might need to guide the LLM better
    • Add examples to the instructions: 
      instructions: |
  When users ask for time, use get_current_time_for_timezone with
  IANA timezone identifiers like 'America/New_York', 'Europe/London', 'Asia/Tokyo'.
  Do not use abbreviations like EST or PST.

Issue 5: “Cannot Modify Agent in Portal”

Symptoms:

  • Portal shows agent but won’t let you edit it
  • Changes don’t save

Solutions:

  1. Edit in VS Code Instead:

    • Keep editing in VS Code where you created it
    • Make changes to the YAML file
    • Press Ctrl+S to save
    • Click “Update Agent on Azure AI Foundry”

  2. Check Permissions:

    • Ensure you have write permissions to the project
    • Verify your Azure account has the necessary roles

  3. Reload Extension:

    • Close and reopen VS Code
    • The extension may need to refresh its connection

Issue 6: “YAML Syntax Error”

Symptoms:

  • Red squiggly lines in the YAML editor
  • Deployment fails with syntax errors

Solutions:

  1. Check Indentation:

    • YAML is strict about indentation
    • Use 2 spaces per indentation level (not tabs)
    • Example: 
      tools:                    # 0 spaces
  - type: mcp           # 2 spaces
    id: get_time        # 4 spaces
    options:            # 4 spaces
      server_url: ...   # 6 spaces
      allowed_tools:    # 6 spaces
        - tool_name     # 8 spaces

  2. Check Quotes:

    • String values don’t need quotes unless they contain special characters
    • URLs should be quoted if they contain colons or slashes: 
      server_url: "https://your-server/sse"  # Good
server_url: https://your-server/sse    # Also acceptable

  3. Use YAML Validator:

Debugging Tips

  1. Enable Verbose Logging:

    • Look for agent execution logs in Azure AI Foundry portal
    • Logs show which tools were called and their results

  2. Test Agent Directly in Portal:

    • Use the Playground interface to test
    • This provides immediate feedback

  3. Check Deployment Status:

    • Verify agent deployment completed successfully
    • Look for any warning or error messages during deployment

  4. Review MCP Server Logs (if accessible):

    • Check your MCP server’s logs for connection or execution errors
    • This helps identify whether issues are on the agent or server side

Getting Help

If you’re still experiencing issues:

  1. Check Microsoft Documentation:

  2. Review MCP Server Documentation:

  3. Check Azure Status:

Next Steps

Enhancements to Consider

  1. Add Multiple MCP Servers:

    tools:
  - type: mcp
    id: time_tools
    options:
      server_url: https://time-server.azurewebsites.net/sse
  - type: mcp
    id: weather_tools
    options:
      server_url: https://weather-server.azurewebsites.net/sse

  2. Combine with Other Tool Types:

    • Add Bing Search for web queries
    • Add Code Interpreter for calculations
    • Add OpenAPI specs for REST API integration

  3. Refine Agent Behavior:

    • Adjust model parameters (temperature, top_p)
    • Enhance instructions with more examples
    • Add context about tool capabilities

  4. Implement Approval Workflows:

    • Configure tools to require approval before execution
    • Useful for sensitive operations

  5. Monitor and Optimize:

    • Track agent usage and performance
    • Analyze which tools are used most
    • Optimize instructions based on user queries

Integration with Applications

To integrate your agent into applications:

  1. Use Agent API:

    • Call the agent via REST API from web apps, mobile apps, or services
    • Azure AI Foundry provides SDK and API documentation

  2. Build Frontend Applications:

    • Create a chat UI in React, Vue, or your preferred framework
    • Call agent endpoints to get responses

  3. Integrate with Existing Systems:

    • Connect agents to business applications
    • Use as decision-making component in workflows

Learning Resources