This practical guide walks you through creating a Model Context Protocol (MCP) server in TypeScript to connect Azure AI Agents with Claude Desktop or any MCP-compatible client. You’ll learn how to build the server, set up the necessary connections, and handle agent interactions programmatically.<\/p>\n
Azure AI Agents provide powerful conversational AI capabilities as part of the Azure AI Foundry ecosystem, but connecting them to desktop applications often requires custom integrations. MCP offers a standardized protocol to bridge these systems, allowing seamless integration between Azure AI Agents and MCP-compatible clients like Claude Desktop.<\/p>\n
Before starting, ensure you have:<\/p>\n
# Create project directory\nmkdir azure-agent-mcp\ncd azure-agent-mcp\n\n# Initialize npm project\nnpm init -y\n\n# Install dependencies\nnpm install @modelcontextprotocol\/sdk zod dotenv @azure\/ai-projects @azure\/identity\n\n# Install dev dependencies\nnpm install -D typescript @types\/node<\/code><\/pre>\nStep 2: Configure TypeScript<\/h3>\n
Create a tsconfig.json file:<\/p>\n
{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"moduleResolution\": \"node\",\n \"esModuleInterop\": true,\n \"outDir\": \".\/dist\",\n \"strict\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true\n },\n \"include\": [\"src\/**\/*\"],\n \"ts-node\": {\n \"esm\": true\n }\n}<\/code><\/pre>\nStep 3: Environment Setup<\/h3>\n
Create an .env file to store your Azure credentials:<\/p>\n
PROJECT_CONNECTION_STRING=your-project-connection-string\nDEFAULT_AGENT_ID=your-default-agent-id # Optional<\/code><\/pre>\nStep 4: Create the MCP Server<\/h3>\n
Now let’s build the server code. Create a file src\/index.ts:<\/p>\n
import { McpServer } from \"@modelcontextprotocol\/sdk\/server\/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol\/sdk\/server\/stdio.js\";\nimport { z } from \"zod\";\nimport * as dotenv from \"dotenv\";\nimport { AIProjectsClient } from \"@azure\/ai-projects\";\nimport { DefaultAzureCredential } from \"@azure\/identity\";\nimport type { MessageRole, MessageContentOutput } from \"@azure\/ai-projects\";\n\ndotenv.config();\n\nconst PROJECT_CONNECTION_STRING = process.env.PROJECT_CONNECTION_STRING;\nconst DEFAULT_AGENT_ID = process.env.DEFAULT_AGENT_ID || \"\";\n\nlet aiClient: AIProjectsClient | null = null;<\/code><\/pre>\nStep 5: Implement Core Functions<\/h3>\n
Let’s add the utility functions that will power our server:<\/p>\n
function isTextContent(\n content: MessageContentOutput\n): content is MessageContentOutput & { type: \"text\"; text: { value: string } } {\n return content.type === \"text\" && !!(content as any).text?.value;\n}\n\n\/**\n * Initialize the Azure AI Agent client\n *\/\nfunction initializeServer(): boolean {\n if (!PROJECT_CONNECTION_STRING) {\n console.error(\n \"ERROR: Missing required environment variable: PROJECT_CONNECTION_STRING\"\n );\n return false;\n }\n\n try {\n const credential = new DefaultAzureCredential();\n aiClient = AIProjectsClient.fromConnectionString(\n PROJECT_CONNECTION_STRING,\n credential\n );\n return true;\n } catch (error) {\n console.error(\n `ERROR: Failed to initialize AIProjectClient: ${\n error instanceof Error ? error.message : String(error)\n }`\n );\n return false;\n }\n}\n\nfunction checkServerInitialized() {\n if (!serverInitialized) {\n return {\n content: [\n {\n type: \"text\" as const,\n text: \"Error: Azure AI Agent server is not initialized. Check server logs for details.\",\n },\n ],\n };\n }\n return null;\n}<\/code><\/pre>\nStep 6 Implement the Query Agent Function<\/h3>\n
This core function handles communication with Azure AI Agents:<\/p>\n
\/**\n * Query an Azure AI Agent and get the response\n *\/\nasync function queryAgent(\n agentId: string,\n userQuery: string,\n existingThreadId?: string\n): Promise<{ response: string; threadId: string }> {\n if (!aiClient) {\n throw new Error(\"AI client not initialized\");\n }\n\n try {\n \/\/ Verify agent exists and is accessible\n await aiClient.agents.getAgent(agentId);\n\n \/\/ Create a new thread or use existing one\n let threadId = existingThreadId;\n if (!threadId) {\n const thread = await aiClient.agents.createThread();\n threadId = thread.id;\n }\n\n \/\/ Add message to thread\n await aiClient.agents.createMessage(threadId, {\n role: \"user\" as MessageRole,\n content: userQuery,\n });\n\n \/\/ Create and process the run\n let run = await aiClient.agents.createRun(threadId, agentId);\n\n \/\/ Poll until the run is complete\n while ([\"queued\", \"in_progress\", \"requires_action\"].includes(run.status)) {\n await new Promise((resolve) => setTimeout(resolve, 1000)); \/\/ Non-blocking sleep\n run = await aiClient.agents.getRun(threadId, run.id);\n }\n\n if (run.status === \"failed\") {\n return {\n response: `Error: Agent run failed: ${\n run.lastError?.message || \"Unknown error\"\n }`,\n threadId,\n };\n }\n\n \/\/ Get the agent's response\n const messages = await aiClient.agents.listMessages(threadId);\n const assistantMessages = messages.data.filter(\n (m) => m.role === \"assistant\"\n );\n const lastMessage = assistantMessages[assistantMessages.length - 1];\n\n let responseText = \"\";\n if (lastMessage) {\n for (const content of lastMessage.content) {\n if (isTextContent(content)) {\n responseText += content.text.value + \"\\n\";\n }\n }\n }\n\n return { response: responseText.trim(), threadId };\n } catch (error) {\n throw new Error(\n `Agent query failed: ${\n error instanceof Error ? error.message : String(error)\n }`\n );\n }\n}<\/code><\/pre>\nStep 7: Register MCP Tools<\/h3>\n
Now, let’s create the MCP server and register the tools:<\/p>\n
\/\/ Initialize server\nconst serverInitialized = initializeServer();\n\n\/\/ Create MCP server\nconst mcp = new McpServer({\n name: \"azure-agent\",\n version: \"1.0.0\",\n description: \"MCP server for Azure AI Agent Service integration\",\n});\n\n\/\/ Register tools\nmcp.tool(\n \"query_agent\",\n \"Query a specific Azure AI Agent\",\n {\n agent_id: z.string().describe(\"The ID of the Azure AI Agent to query\"),\n query: z.string().describe(\"The question or request to send to the agent\"),\n thread_id: z\n .string()\n .optional()\n .describe(\"Thread ID for conversation continuation\"),\n },\n async ({ agent_id, query, thread_id }) => {\n const errorResponse = checkServerInitialized();\n if (errorResponse) return errorResponse;\n\n try {\n const { response, threadId } = await queryAgent(\n agent_id,\n query,\n thread_id\n );\n\n return {\n content: [\n {\n type: \"text\" as const,\n text: `## Response from Azure AI Agent\\n\\n${response}\\n\\n(thread_id: ${threadId})`,\n },\n ],\n };\n } catch (error) {\n return {\n content: [\n {\n type: \"text\" as const,\n text: `Error querying agent: ${\n error instanceof Error ? error.message : String(error)\n }`,\n },\n ],\n };\n }\n }\n);<\/code><\/pre>\nStep 8: Add Default Agent Query Tool<\/h3>\nmcp.tool(\n \"query_default_agent\",\n \"Query the default Azure AI Agent\",\n {\n query: z.string().describe(\"The question or request to send to the agent\"),\n thread_id: z\n .string()\n .optional()\n .describe(\"Thread ID for conversation continuation\"),\n },\n async ({ query, thread_id }) => {\n const errorResponse = checkServerInitialized();\n if (errorResponse) return errorResponse;\n\n if (!DEFAULT_AGENT_ID) {\n return {\n content: [\n {\n type: \"text\" as const,\n text: \"Error: No default agent configured. Set DEFAULT_AGENT_ID environment variable or use query_agent tool.\",\n },\n ],\n };\n }\n\n try {\n const { response, threadId } = await queryAgent(\n DEFAULT_AGENT_ID,\n query,\n thread_id\n );\n\n return {\n content: [\n {\n type: \"text\" as const,\n text: `## Response from Default Azure AI Agent\\n\\n${response}\\n\\n(thread_id: ${threadId})`,\n },\n ],\n };\n } catch (error) {\n return {\n content: [\n {\n type: \"text\" as const,\n text: `Error querying default agent: ${\n error instanceof Error ? error.message : String(error)\n }`,\n },\n ],\n };\n }\n }\n);<\/code><\/pre>\nStep 9: Add List Agents Tool<\/h3>\nmcp.tool(\"list_agents\", \"List all available Azure AI Agents\", {}, async () => {\n const errorResponse = checkServerInitialized();\n if (errorResponse) return errorResponse;\n\n try {\n const agents = await aiClient!.agents.listAgents();\n if (!agents.data || agents.data.length === 0) {\n return {\n content: [\n {\n type: \"text\" as const,\n text: \"No agents found in the Azure AI Agent Service.\",\n },\n ],\n };\n }\n\n let result = \"## Available Azure AI Agents\\n\\n\";\n for (const agent of agents.data) {\n result += `- **${agent.name}** (ID: \\`${agent.id}\\`)\\n`;\n }\n\n if (DEFAULT_AGENT_ID) {\n result += `\\n**Default Agent ID**: \\`${DEFAULT_AGENT_ID}\\``;\n }\n\n return {\n content: [{ type: \"text\" as const, text: result }],\n };\n } catch (error) {\n return {\n content: [\n {\n type: \"text\" as const,\n text: `Error listing agents: ${\n error instanceof Error ? error.message : String(error)\n }`,\n },\n ],\n };\n }\n});<\/code><\/pre>\nStep 10: Create the Main Function<\/h3>\nasync function main() {\n console.error(\"\\n==================================================\");\n console.error(\n `Azure AI Agent MCP Server ${\n serverInitialized ? \"successfully initialized\" : \"initialization failed\"\n }`\n );\n console.error(\"Starting server...\");\n console.error(\"==================================================\\n\");\n\n const transport = new StdioServerTransport();\n await mcp.connect(transport);\n}\n\nmain().catch((error) => {\n console.error(\n `FATAL: ${error instanceof Error ? error.message : String(error)}`\n );\n process.exit(1);\n});<\/code><\/pre>\nStep 11: Build and Run the Server<\/h3>\n
Add the following to your package.json:<\/p>\n
{\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"tsc\",\n \"start\": \"node dist\/index.js\"\n }\n}<\/code><\/pre>\nBuild and run the server:<\/p>\n
npm run build\nnpm start<\/code><\/pre>\nIntegrating with Claude Desktop<\/h2>\n
To integrate your TypeScript MCP server with Claude Desktop, you’ll need to update the Claude Desktop configuration file (claude_desktop_config.json):<\/p>\n
{\n \"mcpServers\": {\n \"azure-agent\": {\n \"command\": \"node\",\n \"args\": [\"\/ABSOLUTE\/PATH\/TO\/azure-agent-mcp\/dist\/index.js\"],\n \"env\": {\n \"PROJECT_CONNECTION_STRING\": \"your-project-connection-string\",\n \"DEFAULT_AGENT_ID\": \"your-default-agent-id\"\n }\n }\n }\n}<\/code><\/pre>\nThis configuration tells Claude Desktop:<\/p>\n
\n- There’s an MCP server named “azure-agent”<\/li>\n
- It should be launched by running the specified Node.js script<\/li>\n
- The necessary environment variables should be passed to the process<\/li>\n<\/ul>\n
Practical Usage Examples<\/h2>\n
Once your MCP server is integrated with Claude Desktop, you can use it in various ways:<\/p>\n
\n- \n
Querying a Specific Agent\nAsk Claude Desktop: “Can you use the azure-agent to check if there are weather alerts in Seattle?”\nBehind the scenes, Claude will use the query_agent<\/code> tool with the appropriate agent ID.<\/p>\n<\/li>\n- \n
Using the Default Agent\nAsk Claude Desktop: “Can you use the default azure agent to summarize the latest NBA news?”\nClaude will automatically use the query_default_agent<\/code> tool for this request.<\/p>\n<\/li>\n- \n
Discovering Available Agents\nAsk Claude Desktop: “What Azure AI agents are available to me?”\nClaude will call the list_agents<\/code> tool and display the results.<\/p>\n<\/li>\n<\/ol>\nConclusion<\/h2>\n
By building an MCP server for Azure AI Agents with TypeScript, you can create a powerful bridge between Azure AI Foundry services and MCP hosts such as Claude Desktop. This sample leverages the strengths of both systems while maintaining a clean separation of concerns through the standardized MCP protocol.<\/p>\n
Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"
Learn how to integrate Azure AI Foundry’s Agent Service with Claude Desktop using the Model Context Protocol (MCP) for powerful integration for MCP clients.<\/p>\n","protected":false},"author":170596,"featured_media":206,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[10,6,7,11,9,8,18],"class_list":["post-197","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-foundry","tag-ai-agents","tag-azure-ai","tag-claude","tag-integration","tag-mcp","tag-model-context-protocol","tag-typescript"],"acf":[],"blog_post_summary":"
Learn how to integrate Azure AI Foundry’s Agent Service with Claude Desktop using the Model Context Protocol (MCP) for powerful integration for MCP clients.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts\/197","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/users\/170596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/comments?post=197"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts\/197\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/media\/206"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/media?parent=197"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/categories?post=197"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/tags?post=197"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}