Skip to main content
Glama
Foundry Agents MCP Server

Foundry Agents MCP Server

by denniszielke

Foundry Agents MCP Server

An MCP (Model Context Protocol) server that exposes Azure AI Foundry agents, workflows, and AI Search vector-database capabilities as MCP tools.

Supports two transports:

  • stdio – for local use with uvx or VS Code Copilot

  • HTTP – for deployment to Azure Container Apps via azd up

Repository layout

src/
  foundry_agents_mcp/     ← MCP server (10 tools across 4 namespaces)
  foundry_agents/         ← Standalone agent & workflow implementations
    definitions/          ← Declarative YAML agent & workflow definitions
    case_study_agent.py   ← deploy-case-study-agent CLI command
    architecture_agent.py ← deploy-architecture-agent CLI command
    project_log_workflow.py ← run-project-log-workflow CLI command
infra/
  main.bicep              ← Container Apps + managed identity + role assignments
  app/server.bicep        ← Container App definition with health probes
  core/security/role.bicep
azure.yaml                ← azd service definition
Dockerfile                ← Multi-stage Alpine build
entrypoint.sh             ← Selects stdio or HTTP transport at startup
.env.sample               ← Template for local environment configuration

Related MCP server: Azure AI Foundry Agent MCP

MCP tool namespaces

Namespace

Tools

agents_*

List agents · Invoke agent · Check status · Get result

search_*

Semantic vector search · Add document to vector DB

index_*

Create project-log index · Ingest project log entry

workflows_*

List sample workflows · Run project-log pipeline


Prerequisites

  • Python 3.10+

  • uv installed

  • An Azure AI Foundry project (for agent tools)

  • An Azure AI Search resource with a vector-capable tier (for search/index tools)

  • An Azure OpenAI resource with a text-embedding model deployed


Quick start with uvx

# Install and run directly from GitHub (no PyPI package required)
uvx --from git+https://github.com/denniszielke/foundry-agents-mcp-server@main foundry-agents-mcp-server

Or with an explicit environment file:

uvx --from git+https://github.com/denniszielke/foundry-agents-mcp-server@main --env-file .env foundry-agents-mcp-server

Configuration

All configuration is driven by environment variables. Copy .env.sample to .env and fill in your values.

Variable

Required

Description

AZURE_AI_PROJECT_ENDPOINT

For agent tools

AI Foundry project endpoint – https://<account>.services.ai.azure.com/api/projects/<project>

AZURE_OPENAI_ENDPOINT

No

OpenAI-compatible endpoint (falls back to AZURE_AI_PROJECT_ENDPOINT)

AZURE_OPENAI_COMPLETION_MODEL_NAME

For workflow tools

Completion model deployment name in the Foundry account

AZURE_OPENAI_EMBEDDING_MODEL

For search/index tools

Embedding model deployment name (default: text-embedding-3-small)

AZURE_OPENAI_EMBEDDING_DIMENSIONS

No

Embedding vector size (default: 1536)

AZURE_AI_SEARCH_ENDPOINT

For search/index tools

Azure AI Search service endpoint URL

AZURE_AI_SEARCH_INDEX_NAME

No

Search index name (default: project-log-index)

APPLICATIONINSIGHTS_CONNECTION_STRING

No

Application Insights connection string for telemetry

Note – When deploying via azd up, all these values are written to .env automatically by infra/write_env.sh. For local development run az login and use DefaultAzureCredential; no API keys are needed.


Claude Desktop configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "foundry-agents": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/denniszielke/foundry-agents-mcp-server@main", "foundry-agents-mcp-server"],
      "env": {
        "AZURE_AI_PROJECT_ENDPOINT": "https://...",
        "AZURE_AI_SEARCH_ENDPOINT": "https://...",
        "AZURE_OPENAI_ENDPOINT": "https://..."
      }
    }
  }
}

Tool reference and example prompts

agents namespace

agents_list_agents

List all agents and workflows available in the Foundry project, including their IDs, models, descriptions, and tool capabilities.

Example prompts

  • "What agents are available in the project?"

  • "List all AI workflows I can invoke"

  • "Show me the agents and their capabilities in this Foundry project"


agents_invoke_agent

Invoke an agent or workflow asynchronously. Returns an invocation ID to track progress.

Parameter

Type

Description

agent_id

string

Agent ID from agents_list_agents

task

string

Task description or question

file_context

string (optional)

Additional text or file content as context

Example prompts

  • "Ask agent <agent_id> to summarize the latest Azure AI announcements"

  • "Invoke the research workflow with task: analyze competitive landscape for AI services"

  • "Send this document to the analysis agent and include the file text as context: <text>"


agents_get_invocation_status

Check whether an agent invocation is still running or has completed.

Parameter

Type

Description

invocation_id

string

Invocation ID from agents_invoke_agent

Possible statuses: queued, in_progress, requires_action, cancelling, cancelled, failed, completed, expired

Example prompts

  • "Check the status of invocation <invocation_id>"

  • "Has my agent task finished? ID: <invocation_id>"

  • "Is the workflow still running for invocation <invocation_id>?"


agents_get_invocation_result

Retrieve the text (and file reference) output from a completed invocation.

Parameter

Type

Description

invocation_id

string

Invocation ID from agents_invoke_agent

Example prompts

  • "Get the results from invocation <invocation_id>"

  • "What did the agent return for ID <invocation_id>?"

  • "Show me the output of the completed workflow: <invocation_id>"


search namespace

search_vector_db

Perform a semantic (vector) search over the project-log index.

Parameter

Type

Description

query

string

Natural language search query

top_k

integer (optional)

Number of results (default: 5)

Example prompts

  • "Find project logs related to Azure Kubernetes Service"

  • "Search for workshop summaries about machine learning"

  • "What meetings discussed security architecture?"

  • "Find blog posts about microservices, return top 10 results"


search_add_to_vector_db

Add a document to the project-log vector index. The content is automatically embedded and stored alongside the metadata.

Parameter

Type

Description

title

string

Document title

content

string

Main text to embed and index

entry_type

string (optional)

workshop, meeting, blog, or repo (default: meeting)

customer_name

string (optional)

Customer or organization name

short_summary

string (optional)

Brief summary

project_name

string (optional)

Associated project name

tags

string (optional)

Comma-separated tags (e.g. "azure,kubernetes")

reference_url

string (optional)

Source URL

architecture

string (optional)

Architecture diagram as JSON or XML

Example prompts

  • "Add this meeting summary to the vector database: title='Azure Workshop', content='...'"

  • "Store a new project log entry about our Kubernetes migration discussion"

  • "Index this blog post with tags: azure, containers, devops"


index namespace

index_create_project_log_index

Create the project-log Azure AI Search index with the correct schema and HNSW vector configuration. Safe to call when the index already exists.

Schema fields

Field

Type

Notes

id

String (key)

Auto-generated UUID

title

String

Searchable, filterable, sortable

type

String

Filterable, facetable (workshop, meeting, blog, repo)

customer_name

String

Filterable, facetable

short_summary

String

Searchable

context

String

Searchable (full body text)

context_vector

Collection(Single)

HNSW vector search field

project_name

String

Filterable, facetable

tags

Collection(String)

Filterable, facetable

reference_url

String

Searchable

architecture

String

Searchable

creation_date

DateTimeOffset

Filterable, sortable

modified_date

DateTimeOffset

Filterable, sortable

Example prompts

  • "Set up the project log search index"

  • "Create the Azure AI Search index for storing project summaries"

  • "Initialize the vector database schema for project logs"


index_ingest_project_log

Ingest a single project log entry into the index. The index is created automatically if it does not exist.

Parameter

Type

Description

title

string

Log entry title

entry_type

string

workshop, meeting, blog, or repo

customer_name

string

Customer or organization name

short_summary

string

Brief summary (1–2 sentences)

context

string

Full context text (will be embedded)

project_name

string (optional)

Project name

tags

string (optional)

Comma-separated tags

reference_url

string (optional)

Source URL

architecture

string (optional)

Architecture diagram as JSON or XML

Example prompts

  • "Add a workshop log: title='Azure AI Day', entry_type='workshop', customer_name='Contoso', context='...'"

  • "Index a new meeting summary about the cloud migration project"

  • "Store this repo documentation with tags: python, mcp, azure"


Sample agents and workflow

The foundry_agents package provides two sample agents and a pipeline workflow that work independently of the MCP server.

Deploy agents to Azure AI Foundry

Register the sample agents in your Foundry project (they then appear in agents_list_agents and can be invoked with agents_invoke_agent):

deploy-case-study-agent      # registers CaseStudyAgent
deploy-architecture-agent    # registers ArchitectureAgent

Run the project-log workflow

Fetch a Microsoft customer story, extract metadata, generate an architecture diagram, and store everything in the vector index – all in one command:

run-project-log-workflow \
  --url "https://www.microsoft.com/en/customers/story/25676-commerzbank-ag-azure-ai-foundry-agent-service" \
  --project "Commerzbank AI Platform"

Or trigger the same pipeline from the MCP server:

Run the project log workflow for https://www.microsoft.com/en/customers/story/...

The workflow automatically uses deployed Foundry agents when available and falls back to direct Azure OpenAI inference otherwise.


Deploy to Azure Container Apps

The server can be deployed to Azure Container Apps with a single command using the Azure Developer CLI (azd).

What gets provisioned

Resource

Purpose

Virtual Network

Container Apps environment runs VNet-integrated (always)

Container Apps Environment

Hosts the MCP server; set USE_PRIVATE_INGRESS=true for internal-only access

Azure Container Registry

Stores the Docker image

Log Analytics + Application Insights

Telemetry and distributed traces

Azure AI Foundry (AIServices + project)

Agents API + model deployments (completion + embedding)

Azure AI Search

Vector search index for the project log

User-assigned Managed Identity

Passwordless auth – assigned Azure AI Developer, Cognitive Services OpenAI User, Search Index Data Contributor, and AcrPull roles

Infra folder structure

infra/
  abbreviations.json          ← Azure resource name prefixes
  main.bicep                  ← Subscription-scoped orchestrator
  main.parameters.json        ← azd parameter file
  ai/
    foundry.bicep             ← AIServices account + Foundry project + model deployments
    search.bicep              ← Azure AI Search
  app/
    server.bicep              ← MCP server Container App + identity
  core/
    host/
      vnet.bicep              ← VNet with aca-apps subnet (always deployed)
      container-apps.bicep    ← Environment + registry orchestration
      container-apps-environment.bicep  ← Managed environment (usePrivateIngress flag)
      container-app.bicep     ← Container App with health probes + role assignments
      container-app-upsert.bicep
      container-registry.bicep
    monitor/
      monitoring.bicep        ← Log Analytics + Application Insights
      loganalytics.bicep
      applicationinsights.bicep
    security/
      foundry-access.bicep    ← Azure AI Developer + Cognitive Services OpenAI User
      registry-access.bicep   ← AcrPull
      search-access.bicep     ← Search Index Data Contributor

Quick deploy

# 1. Login
azd auth login

# 2. Create an azd environment
azd env new foundry-mcp
azd env set AZURE_LOCATION swedencentral   # or eastus2, westus3, northcentralus

# 3. (Optional) private ingress – accessible only from within the VNet
azd env set USE_PRIVATE_INGRESS true

# 4. Provision infrastructure (no local Docker required)
azd up

azd up will:

  1. Provision all resources (VNet, Container Apps, Foundry, Search, monitoring)

  2. Run infra/write_env.sh to populate .env with all endpoint values

Build and deploy the container

The container image is built remotely using Azure Container Registry (ACR) – no local Docker installation is required. After azd up has provisioned the infrastructure, run:

# Build in ACR and deploy the Container App
./azd-hooks/deploy.sh foundry-mcp   # pass your azd environment name

The script will:

  1. Build the Docker image remotely in ACR via az acr build

  2. Deploy the Container App via a Bicep deployment (infra/app/server.bicep)

  3. Print the MCP server URL

Private ingress

When USE_PRIVATE_INGRESS=true the Container Apps environment is configured as internal: true and the Container App ingress is set to external: false. The MCP server is then only reachable from within the VNet (e.g. via a jump host, VPN, or another Container App in the same environment).

Connect VS Code Copilot to the deployed server

# Find the URL
cat .env | grep MCP_SERVER_URL
  1. Open Command Palette in VS Code → MCP: Add Server → HTTP.

  2. Enter the URL from .env (e.g. https://<app-fqdn>/mcp).

  3. All 10 Foundry Agent tools are now available in Copilot Chat.

Run locally with HTTP transport

# Start the HTTP server (same code, same image)
uvicorn foundry_agents_mcp.server:http_app --host 0.0.0.0 --port 8000

# Test the health probe
curl http://localhost:8000/health
# → {"status":"healthy","service":"foundry-agents-mcp-server"}

Monitoring

OpenTelemetry tracing is enabled automatically when APPLICATIONINSIGHTS_CONNECTION_STRING is set. Every MCP tool call and HTTP request is traced via azure-monitor-opentelemetry.

azd monitor   # open the Application Insights dashboard in the portal

Tear down

azd down

Development

# Clone and install in editable mode
git clone https://github.com/denniszielke/foundry-agents-mcp-server
cd foundry-agents-mcp-server
pip install -e ".[dev]"

# Run locally (stdio)
python -m foundry_agents_mcp

License

MIT

Available Tools

10 tools
agents_get_invocation_resultA

Retrieve the text or file results from a completed agent or workflow invocation.

Inputs: invocation_id (required). Returns: result

agents_get_invocation_statusB

Check the status of an agent or workflow invocation.

Inputs: invocation_id (required). Returns: result

agents_invoke_agentA

Invoke an agent or workflow with a task and optional context.

Creates a new conversation thread, submits the task, and returns an invocation ID that can be used with agents_get_invocation_status and agents_get_invocation_result.

Inputs: task (required), agent_id (required), file_context. Returns: result

agents_list_agentsA

List all available agents and workflows in the Azure AI Foundry project.

Returns a formatted list of published agents including their IDs, models, descriptions, and available tools/capabilities.

Example prompts:

  • "What agents are available in the project?"

  • "List all AI workflows I can invoke"

  • "Show me the agents and their capabilities in this Foundry project"

Inputs: no named parameters. Returns: result

index_create_project_log_indexA

Create the project log search index in Azure AI Search.

Sets up the index schema including vector search capabilities for semantic similarity search on the context field. The schema supports: title, type, customer_name, short_summary, context (+ embedding vector), project_name, tags, reference_url, architecture, creation_date, modified_date.

Safe to call if the index already exists – it will return a confirmation without modifying the existing index.

Example prompts:

  • "Set up the project log search index"

  • "Create the Azure AI Search index for storing project summaries"

  • "Initialize the vector database schema for project logs"

Inputs: no named parameters. Returns: result

index_ingest_project_logB

Ingest a project log entry into the Azure AI Search index with vector embeddings.

Generates a vector embedding for the context field and stores the complete project log entry. Creates the index automatically if it does not exist.

Inputs: title (required), context (required), entry_type (required), customer_name (required), +5 more. Returns: result

search_add_to_vector_dbA

Add a new document to the project vector database.

Generates a vector embedding for the content and stores the document in the Azure AI Search index for future semantic searches.

Inputs: title (required), content (required), tags, entry_type, +5 more. Returns: result

search_vector_dbA

Search the project vector database using semantic similarity.

Generates a vector embedding for the query and returns the most similar documents from the Azure AI Search index.

Inputs: query (required), top_k. Returns: result

workflows_list_sample_workflowsA

List the available sample workflow and agent definitions.

Returns the names, locations, and descriptions of the built-in declarative YAML files in src/foundry_agents/definitions/ and the available CLI deployment/run commands.

Example prompts:

  • "What sample workflows are available?"

  • "Show me the built-in workflow definitions"

  • "List the declarative agent templates I can deploy to Foundry"

Inputs: no named parameters. Returns: result

workflows_run_project_log_workflowA

Run the full project-log ingestion workflow for a Microsoft customer story.

This workflow sequentially invokes two declarative agents:

  1. CaseStudyAgent – fetches the story page and extracts: title, customer name, summary, context, tags, and the source URL.

  2. ArchitectureAgent – generates a structured JSON architecture diagram from the case study context and technology tags.

The combined result is stored as a single entry in the Azure AI Search project-log vector index.

If CaseStudyAgent and ArchitectureAgent have been deployed to Azure AI Foundry (via deploy-case-study-agent / deploy-architecture-agent), they are invoked via the Foundry API so that the run is visible in the project telemetry. Otherwise the same logic runs locally against Azure OpenAI directly.

Inputs: story_url (required), project_name. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation3/5

    The agents_* and workflows_* tools are fairly distinguishable, but there's notable overlap between index_ingest_project_log and search_add_to_vector_db — both add a document to the same vector index. search_vector_db vs index_* tools are clear, but the ingest/add duplication causes potential misselection.

    Naming Consistency3/5

    The server mixes three namespaces: agents_*, index_*, and search_*, each with a verb_noun pattern. However, search_vector_db and search_add_to_vector_db break consistency — one names the action (search) while the other uses search_ as a namespace prefix, so search_* doesn't consistently mean a namespace or an action.

    Tool Count4/5

    10 tools is a reasonable and well-scoped count for a server handling both agent invocation and vector-database search. Each tool has a clear role in the two primary workflows, though the redundant ingest/add tools pad the count slightly.

    Completeness4/5

    The agent workflow covers list/invoke/status/result, which is complete for async invocation. The vector DB side has create-index, ingest, add, and search. Minor gaps exist — there's no delete or update for vector documents, and the result retrieval is separated from status with no explicit error-handling tool — but core lifecycle needs are met.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers