토픽 추가 및 관리

툴링 모듈은 개발자가 모델 컨텍스트 프로토콜(MCP) 서버를 AI 에이전트 워크플로에서 발견하고, 구성하며, 통합할 수 있도록 도와줍니다. MCP 서버는 외부 기능을 AI 에이전트가 호출할 수 있는 도구 형태로 제공합니다. 사용 가능한 툴링 서버에 대한 개요는 Agent 365 툴링 서버를 참조하세요.

요청과 응답 흐름 시연

개요

Agent 365 툴링 통합은 다음과 같은 워크플로를 따릅니다.

MCP 서버 구성 - Agent 365 CLI를 사용하여 MCP 서버를 탐색하고 추가합니다
매니페스트 생성 - CLI는 서버 구성을 포함한 ToolingManifest.json 파일을 프로젝트 폴더에 생성합니다.
청사진에 권한 적용 - 전역 관리자가 a365 setup all(최초 설정 시) 또는 a365 setup permissions mcp(청사진이 이미 존재하는 경우) 명령을 실행하여 에이전트 청사진에 OAuth2 권한을 부여합니다. 어느 경우든, 해당 명령은 ToolingManifest.json을 읽고 관리자 승인이 필요합니다. 이 단계는 항상 매니페스트에 서버를 추가하는 작업과 별도로 수행됩니다.
코드에 통합 - 매니페스트를 로드하고 오케스트레이터에 도구를 등록합니다.
도구 호출 - 에이전트는 실행 중에 작업을 수행하기 위해 도구를 호출합니다.

필수 구성 요소

MCP 서버를 구성하기 전에 필요한 항목:

Agent 365 CLI 설치 및 설정
.NET 8.0 SDK 이상 - 다운로드
Microsoft 365 테넌트의 전역 관리자 권한

에이전트 ID 설정

에이전트형 인증을 사용 중이라면, MCP 서버를 구성하기 전에 에이전트 등록 프로세스를 완료하여 에이전트 ID를 생성하세요. 이 과정은 Entra 에이전트 ID와 에이전트 사용자를 생성하며, 이를 통해 에이전트가 MCP 도구를 인증하고 액세스할 수 있도록 합니다.

OBO 인증 설정

에이전트 인증 대신 On-Behalf-Of(OBO) 인증을 사용하면, 별도의 에이전트 사용자 계정 없이 위임된 사용자 권한을 사용해 MCP 도구에 액세스할 수 있습니다. OBO 흐름에서는 에이전트가 사용자의 위임 토큰을 교환하여 사용자를 대신해 작업을 수행합니다.

OBO 흐름이 어떻게 작동하는지에 대한 자세한 내용은 인증 흐름을 참조하세요. 완전한 구현 예시는 Microsoft 365 에이전트 SDK의 OBO 권한 샘플을 참조하세요.

서비스 주체 설정

이 일회성 설정 스크립트를 실행하여 테넌트 내 Agent 365 Tools의 서비스 주체를 생성하세요.

중요

이 작업은 테넌트마다 한 번만 수행되며, 전역 관리자 권한이 필요합니다.

New-Agent365ToolsServicePrincipalProdPublic.ps1 스크립트를 다운로드하세요.
PowerShell을 관리자 권한으로 열고 스크립트 디렉터리로 이동하세요.

스크립트를 실행합니다.

.\New-Agent365ToolsServicePrincipalProdPublic.ps1

메시지가 표시되면 Azure 자격 증명을 사용하여 로그인하세요.

작업이 완료되면, 테넌트는 에이전트 개발과 MCP 서버 구성을 위한 준비가 완료됩니다.

MCP 서버 구성

Agent 365 CLI를 사용하여 에이전트용 MCP 서버를 검색, 추가 및 관리하세요. 사용 가능한 MCP 서버와 지원 기능의 전체 목록은 MCP 서버 카탈로그를 참조하세요.

사용 가능한 서버 검색

구성할 수 있는 모든 MCP 서버 목록:

a365 develop list-available

MCP 서버 추가

에이전트 구성에 MCP 서버를 하나 이상 추가합니다.

a365 develop add-mcp-servers mcp_MailTools

중요

이 명령은 프로젝트 폴더의 ToolingManifest.json만 업데이트하며, 청사진에 어떠한 권한도 부여하지 않습니다. 권한이 적용되는 방식은 설정 과정의 어느 단계에 있느냐에 따라 달라집니다.

초기 설정 전: 먼저 a365 develop add-mcp-servers를 실행한 후 a365 setup all을 진행하세요. setup all 명령에는 청사진 생성 시 MCP 권한 단계가 포함되어 있습니다.
청사진이 이미 존재할 경우: 전역 관리자가 a365 setup permissions mcp를 별도로 실행해야 합니다. 관리자의 a365.config.json에는 업데이트된 ToolingManifest.json을 포함하는 프로젝트 폴더를 가리키는 deploymentProjectPath가 설정되어 있어야 합니다. 이 단계가 완료되기 전까지는 새로운 MCP 서버 권한이 청사진에 표시되지 않습니다.

구성된 서버 목록

현재 설정된 MCP 서버 보기:

a365 develop list-configured

MCP 서버 제거

구성에서 MCP 서버 제거:

a365 develop remove-mcp-servers mcp_MailTools

전체 CLI 명령어 참조는 a365 개발 명령을 참조하세요.

테스트용으로 모형 공구 서버 사용

테스트 및 개발을 위해서는 실제 MCP 서버에 연결하는 대신 Agent 365 CLI 모의 툴링 서버를 사용합니다. 모의 서버는 MCP 서버와의 상호작용을 모방하여 인증과 같은 외부 종속성 없이 로컬 환경에서 에이전트를 테스트할 수 있습니다.

모의 서버는 로컬 개발 및 테스트에 다음과 같은 이점을 제공합니다.

오프라인 개발: 인터넷 연결이나 외부 의존 없이 에이전트를 테스트합니다.
일관된 테스트: 경계 상황 테스트에 대해 예측 가능한 응답을 받을 수 있습니다.
디버깅: 모든 요청과 응답을 실시간으로 확인할 수 있습니다
빠른 반복: 외부 API 호출을 기다릴 필요도 없고, 복잡한 테스트 환경을 구축할 필요가 없습니다.

a365 develop start-mock-tooling-server 명령을 사용하여 모의 툴링 서버를 시작하세요.

모의 툴링 서버를 설정 및 구성하는 방법을 확인하세요.

참고

매니페스트를 구성하고 도구를 에이전트에 통합하는 다음 섹션들은 모의 툴링 서버를 사용하든 실제 MCP 서버를 사용하든 같은 방식으로 적용됩니다. MCP_PLATFORM_ENDPOINT 환경 변수를 프로덕션 엔드포인트가 아닌 모의 서버를 가리키도록 설정하세요(예: http://localhost:5309).

툴링 매니페스트 이해

a365 develop add-mcp-servers를 실행하면, CLI가 모든 MCP 서버의 구성 정보를 담은 ToolingManifest.json 파일을 생성합니다. 에이전트 런타임은 이 매니페스트를 사용하여 어떤 서버를 사용할 수 있는지와 인증 방법을 파악합니다.

매니페스트 구조

예 ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

매니페스트 매개 변수

각 MCP 서버 항목은 다음과 같은 내용을 포함합니다.

매개 변수	설명
mcpServerName	MCP 서버의 표시 이름입니다.
mcpServerUniqueName	MCP 서버 인스턴스의 고유 식별자입니다.
범위	MCP 서버의 기능(예: 메일 작업용 `McpServers.Mail.All`)에 접근하기 위해 필요한 OAuth 범위입니다. `add-mcp-servers` 명령어는 이 값을 MCP 서버 카탈로그에서 가져옵니다.
대상 그룹	대상 API 리소스를 식별하는 Microsoft Entra ID URI입니다. `add-mcp-servers` 명령어는 이 값을 MCP 서버 카탈로그에서 가져옵니다.

참고

Agent 365 CLI는 MCP 서버를 추가할 때 scope 및 audience 값을 자동으로 채웁니다. 이 값들은 MCP 서버 카탈로그에서 가져온 것이며, 각 MCP 서버에 접근하는 데 필요한 권한을 정의합니다.

에이전트에 도구 통합하기

툴링 매니페스트를 생성한 후, 설정된 MCP 서버를 에이전트 코드에 통합하세요. 이 섹션에서는 선택적 검사 단계와 필요한 통합 단계를 다룹니다.

툴 서버 목록(선택 사항)

팁

이 단계는 선택 사항입니다. 도구 서버 구성 서비스를 사용하여 도구 명세서에서 사용 가능한 도구 서버를 검사한 후 오케스트레이터에 추가하세요.

툴 서버 구성 서비스를 사용하여 툴링 매니페스트에서 에이전트가 사용할 수 있는 툴 서버를 확인하세요. 이 방법을 사용하면 다음을 수행할 수 있습니다.

ToolingManifest.json 파일에서 모든 구성된 MCP 서버를 조회합니다.
서버 메타데이터와 기능을 조회합니다.
등록 전에 서버 사용 가능 여부를 확인합니다.

도구 서버를 나열하는 메서드는 핵심 툴링 패키지에 포함되어 있습니다.

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

매개 변수:

매개 변수	Type	Description	예상 값	필수/선택
`agentic_app_id`	str	에이전트 애플리케이션 인스턴스의 고유 식별자	유효한 에이전트 애플리케이션 ID 문자열	필수
`auth_token`	str	MCP 서버 게이트웨이를 이용한 인증을 위한 전달자 토큰	유효한 OAuth 전달자 토큰	필수

패키지: microsoft_agents_a365.tooling

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

매개 변수:

매개 변수	Type	Description	예상 값	필수/선택
`agentInstanceId`	string	에이전트 인스턴스의 고유 식별자	유효한 에이전트 인스턴스 ID 문자열	필수
`authToken`	string	MCP 서버 게이트웨이를 이용한 인증을 위한 전달자 토큰	유효한 OAuth 전달자 토큰	필수

패키지: @microsoft/agents-a365-tooling

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

매개 변수:

매개 변수	Type	Description	예상 값	필수/선택
`agentInstanceId`	string	에이전트 인스턴스의 고유 식별자	유효한 에이전트 인스턴스 ID 문자열	필수
`authToken`	string	MCP 서버 게이트웨이를 이용한 인증을 위한 전달자 토큰	유효한 OAuth 전달자 토큰	필수

패키지: Microsoft.Agents.A365.Tooling.Services

오케스트레이터로 도구 등록

프레임워크별 확장 메서드를 사용하여 모든 MCP 서버를 오케스트레이션 프레임워크에 등록하세요.

AddToolServersToAgentAsync (.NET)
add_tool_servers_to_agent (Python)
addToolServersToAgent (Node.js)

다음 메서드들:

구성된 MCP 서버의 모든 도구를 오케스트레이터에 등록하세요
인증 및 연결 정보를 자동으로 설정하세요
에이전트가 즉시 호출할 수 있도록 도구를 사용 가능하게 하세요

오케스트레이터 확장 프로그램을 선택하세요

Agent 365 툴링 모듈은 다양한 오케스트레이션 프레임워크를 위한 전용 확장 패키지를 제공합니다.

microsoft_agents_a365.tooling: 핵심 툴링 기능
microsoft_agents_a365.tooling.extensions.agentframework: Agent Framework 통합
microsoft_agents_a365.tooling.extensions.azureaifoundry: Azure AI Foundry 통합
microsoft_agents_a365.tooling.extensions.openai: OpenAI 통합
microsoft_agents_a365.tooling.extensions.semantickernel: 의미 체계 커널 통합

참고

a365 develop add-mcp-servers을 실행하면, CLI가 MCP 서버 카탈로그에서 OAuth 스코프와 Audience 값을 자동으로 가져와 ToolingManifest.json에 기록합니다. 확장 메서드는 이러한 값을 활용하여 런타임에 인증을 자동으로 구성하므로, 에이전트 코드에서 별도의 수동 설정이 필요하지 않습니다. 하지만 에이전트가 프로덕션 환경에서 해당 권한을 사용하려면, 여전히 전역 관리자가 에이전트 청사진에 이 권한을 부여해야 합니다. 이는 a365 setup all(최초 설정 시) 또는 a365 setup permissions mcp(청사진이 이미 존재하는 경우)를 통해 수행할 수 있습니다.

자세한 구현 예시들은 Agent 365 샘플을 참고하십시오.

구현 예시

Agent 365 툴링의 다양한 오케스트레이션 프레임워크 통합 방법을 아래 예시에서 보여줍니다.

Python와 OpenAI

이 예제는 Python 애플리케이션에서 MCP 도구를 OpenAI와 통합하는 방법을 보여줍니다.

1. 가져오기 문 추가

툴링 모듈과 OpenAI 확장 기능에 접근하기 위해 필요한 import 문을 추가하세요.

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. 툴링 서비스 초기화

구성 서비스와 도구 등록 서비스의 인스턴스를 생성하세요.

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. OpenAI 에이전트에 MCP 도구 등록하기

모든 구성된 MCP 도구를 OpenAI AI 에이전트에 등록하려면 add_tool_servers_to_agent 메서드를 사용하세요. 이 메서드는 에이전트 기반 인증 시나리오와 비에이전트 기반 인증 시나리오를 모두 처리합니다.

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

메서드 매개 변수

다음 표는 add_tool_servers_to_agent와 함께 사용할 매개변수를 설명합니다.

매개 변수	설명
`agent`	도구를 등록할 OpenAI 에이전트 인스턴스입니다.
`agentic_app_id`	에이전트의 고유 식별자(에이전트 기반 앱 ID).
`auth`	사용자 권한 부여 컨텍스트.
`context`	Agents SDK의 현재 대화 턴 컨텍스트. 사용자 ID, 대화 메타데이터, 인증 컨텍스트를 제공하여 안전한 도구 등록을 지원합니다.
`auth_token`	(선택 사항) 비에이전트 방식 인증 시나리오에서 사용하는 전달자 토큰.

4. 초기화 시 호출

에이전트를 실행하기 전에 초기화 시 설정 메서드를 호출하세요.

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

add_tool_servers_to_agent 메서드는 자동으로 다음과 같은 작업을 수행합니다.

ToolingManifest.json 파일에서 모든 MCP 서버를 로드합니다.
각 도구를 OpenAI 에이전트에 등록합니다.
매니페스트 구성에 따라 인증을 설정합니다.
도구를 에이전트가 사용할 수 있게 합니다.

JavaScript와 LangChain

이 예시는 JavaScript 또는 TypeScript 애플리케이션에서 MCP 도구를 LangChain과 통합하는 방법을 설명합니다.

1. 가져오기 문 추가

Tooling 모듈과 LangChain 확장 기능에 접근하기 위해 필요한 가져오기 문을 추가하세요.

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

2. 툴링 서비스 초기화

도구 등록 서비스의 인스턴스를 생성하세요.

const toolService = new McpToolRegistrationService();

3. LangChain 에이전트에 MCP 도구 등록하기

addToolServersToAgent 메서드를 사용하여 구성된 모든 MCP 도구를 LangChain 에이전트에 등록하세요. 이 메서드는 에이전트 기반 인증 시나리오와 비에이전트 기반 인증 시나리오를 모두 처리합니다.

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

메서드 매개 변수

다음 표는 addToolServersToAgent 메서드와 함께 사용할 매개변수를 설명합니다.

매개 변수	설명
`agent`	도구를 등록할 LangChain ReactAgent 인스턴스.
`agentUserId`	에이전트 사용자의 고유 식별자. 에이전트 인증을 사용하지 않는 경우 빈 문자열(`''`)을 사용하세요.
`authorization`	사용자 권한 부여 컨텍스트.
`turnContext`	Agents SDK의 현재 대화 턴 컨텍스트. 사용자 ID, 대화 메타데이터, 인증 컨텍스트를 제공하여 안전한 도구 등록을 지원합니다.
`authToken`	(선택 사항) 비에이전트 방식 인증 시나리오에서 사용하는 전달자 토큰.

4. 초기화 시 호출

초기화 시 addToolServersToAgent 메서드를 호출하여 에이전트에 MCP 도구를 등록하세요.

addToolServersToAgent 메서드는 자동으로 다음과 같은 작업을 수행합니다.

ToolingManifest.json 파일에서 모든 MCP 서버를 로드합니다.
도구를 LangChain 에이전트에 등록합니다.
매니페스트 구성에 따라 인증을 설정합니다.
도구를 에이전트가 사용할 수 있게 합니다.

.NET와 의미 체계 커널

이 예제는 .NET 애플리케이션에서 MCP 도구를 의미 체계 커널과 통합하는 방법을 보여줍니다.

1. 가져오기 문 추가

툴링 모듈 및 의미 체계 커널 확장에 접근하기 위해 필요한 네임스페이스를 추가하세요.

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

2. 종속성 주입을 사용하여 서비스 등록

도구 서비스를 종속성 주입 컨테이너에 등록하여 클래스에서 사용할 수 있도록 하세요.

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

3. 프라이빗 필드 선언 추가

도구 등록 서비스 참조를 보관할 개인 필드를 선언하세요.

private readonly IMcpToolRegistrationService _toolsService;

4. 의미 체계 커널로 MCP 도구 등록

AddToolServersToAgentAsync 확장 메서드를 사용하여 모든 구성된 MCP 도구를 의미 체계 커널 인스턴스에 등록하세요. 이 메서드는 에이전트 기반 인증 시나리오와 비에이전트 기반 인증 시나리오를 모두 처리합니다.

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

참고

여러 가지 메서드 오버로드를 사용할 수 있습니다. 단순화된 버전은 기본 인증 구성을 사용하며, 명시적 버전은 사용자 정의 인증 처리기 지정을 허용합니다.

메서드 매개 변수

다음 표는 AddToolServersToAgentAsync와 함께 사용할 매개변수를 설명합니다.

매개 변수	설명
`kernel`	도구를 등록할 의미 체계 커널 인스턴스. Kernel은 AI 서비스, 플러그인 및 함수 실행을 조율합니다.
`userAuthorization`	사용자 권한 부여 컨텍스트.
`authHandlerName`	UserAuthorization System용 인증 처리기 이름.
`turnContext`	에이전트 SDK에서 제공하는 현재 대화 턴 컨텍스트(한 사용자 메시지와 에이전트 응답 주기)입니다. 사용자 ID, 대화 메타데이터, 인증 컨텍스트를 제공하여 안전한 도구 등록을 지원합니다.
`authToken`	(선택 사항) 비에이전트 방식 인증 시나리오에서 사용하는 전달자 토큰.

AddToolServersToAgentAsync 메서드는 자동으로 다음과 같은 작업을 수행합니다.

ToolingManifest.json 파일에서 모든 MCP 서버를 로드합니다.
MCP 서버의 도구를 의미 체계 커널에 등록합니다.
매니페스트 구성에 따라 인증을 설정합니다.
도구를 에이전트가 사용할 수 있게 합니다.

전체 동작 예시는 Agent 365 샘플 리포지토리를 참조하세요.

Agent 365 MCP 서버를 이용할 수 있는 다른 방법

Agent 365 SDK 외에도, 다른 개발 환경을 통해 Agent 365 MCP 서버에 액세스할 수 있습니다.

Visual Studio Code - 맞춤형 개발 워크플로를 위해 MCP 서버에 직접 연결할 수 있습니다.
Microsoft Copilot Studio - 로우코드환경을 통해 MCP 서버를 대화형 흐름에 통합합니다.
Azure AI Foundry - 완전한 SDK 지원과 고급 오케스트레이션 기능을 갖춘 MCP 서버를 사용할 수 있습니다.

이들 플랫폼 전반에 걸쳐 사용 가능한 MCP 서버와 통합 옵션에 대한 완전한 개요는 Agent 365 툴링 서버 개요를 참조하세요.

BYO(Bring Your Own) MCP 서버

Bring Your Own(BYO) MCP 서버 기능은 사용자가 자신의 외부 MCP 서버를 Microsoft Agent 365에 등록하여 Microsoft 365 관리 센터에서 중앙 관리, 승인 및 모니터링할 수 있도록 지원합니다. 이 서버들은 Agent 365 툴링 게이트웨이를 통해 라우팅되어, 관리자가 승인, 액세스 및 정책을 제어할 수 있게 하고, 보안팀이 텔레메트리를 통해 사용량을 추적할 수 있도록 합니다. 개발자는 Agent 365 CLI를 사용하여 MCP 서버를 등록한 후, 관리자가 등록을 검토하고 승인하며 권한을 부여합니다. 승인된 서버는 지원되는 클라이언트 도구에서 사용될 수 있으며, 지속적인 모니터링을 통해 모든 통합의 준수와 가시성을 확보합니다.

자세한 지침은 Bring your own (BYO) MCP 서버를 참조하세요.

에이전트 테스트

에이전트에 MCP 도구를 통합한 후, 도구 호출을 테스트하여 올바르게 작동하고 다양한 시나리오를 처리할 수 있는지 확인하세요. 테스트 가이드를 따라 환경을 설정하세요. 그런 다음, 중점적으로 테스트 도구 호출 섹션에 집중하여 MCP 도구가 기대대로 작동하는지 확인하세요. 또한 모의 툴링 서버를 사용해 인증 없이 MCP 서버 연결과 도구 호출을 테스트해보세요.

가시성 추가

에이전트에 가시성을 추가하여 MCP 도구 호출을 모니터링하고 추적하세요. 가시성 기능을 추가하면 성능을 추적하고, 문제를 디버깅하며, 도구 사용 패턴을 이해할 수 있습니다. 추적 및 모니터링 구현 방법에 대해 자세히 알아보세요.

문제 해결

이 섹션에서는 MCP 서버와 도구를 구성하고 사용할 때 흔히 발생하는 문제를 나열합니다.

팁

Agent 365 문제 해결 가이드에는 고급 문제 해결 권장 사항, 모범 사례, 그리고 Agent 365 개발 라이프사이클의 각 단계별 문제 해결 콘텐츠에 대한 링크가 포함되어 있습니다.

MCP 서버 및 도구 문제

증상:

도구 호출 실패.
"MCP 서버를 찾을 수 없습니다" 오류.
도구 호출 시 권한 거부 오류.

근본 원인:

MCP 서버가 구성되어 있지 않습니다.
권한이 없습니다.
서비스 주체가 설정되어 있지 않습니다.
모의 서버와 운영 서버 간의 혼동.

해결 방법: 문제를 해결하기 위해 다음 방법을 시도해 보세요.

MCP 서버가 설정되어 있는지 확인하세요

설정된 서버를 나열하고 빠진 서버를 추가하세요.

# List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

서비스 주체 존재 여부 확인

툴링에 필요한 서비스 주체가 생성되어 있는지 확인하세요.

# Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

초기 개발 및 테스트에는 모의 서버를 사용하세요

프로덕션 툴링 컴포넌트 없이 에이전트의 나머지 부분을 테스트하고 싶다면, 초기 로컬 개발 및 테스트를 위해 모의 툴링 서버를 사용하세요.
```
# Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309
```
모의 툴링 서버에 대해 알아보세요.
관리 센터에서 권한 확인

에이전트에 필요한 MCP 권한이 있는지 확인합니다.
- Azure Portal에서 에이전트 청사진의 API 권한이 모든 MCP 서버 권한을 표시하는지 확인하세요.
확인:
```
# Test a tool call in Agents Playground
# Should execute without permission errors
```

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-07-30

토픽 추가 및 관리

개요

필수 구성 요소

에이전트 ID 설정

OBO 인증 설정

서비스 주체 설정

MCP 서버 구성

사용 가능한 서버 검색

MCP 서버 추가

구성된 서버 목록

MCP 서버 제거

테스트용으로 모형 공구 서버 사용

툴링 매니페스트 이해

매니페스트 구조

매니페스트 매개 변수

에이전트에 도구 통합하기

툴 서버 목록(선택 사항)

오케스트레이터로 도구 등록

오케스트레이터 확장 프로그램을 선택하세요

구현 예시

Python와 OpenAI

1. 가져오기 문 추가

2. 툴링 서비스 초기화

3. OpenAI 에이전트에 MCP 도구 등록하기

메서드 매개 변수

4. 초기화 시 호출

Agent 365 MCP 서버를 이용할 수 있는 다른 방법

BYO(Bring Your Own) MCP 서버

에이전트 테스트

가시성 추가

문제 해결

MCP 서버 및 도구 문제

피드백

추가 리소스