Azure Functions에 대한 MCP 도구 트리거

MCP 도구 트리거를 사용하여 MCP(모델 콘텐츠 프로토콜) 서버에서 도구 엔드포인트를 정의합니다. 클라이언트 언어 모델 및 에이전트는 도구를 사용하여 코드 조각 저장 또는 액세스와 같은 특정 작업을 수행할 수 있습니다.

설정 및 구성 세부 정보에 대한 자세한 내용은 개요를 참조하세요.

예시

비고

C#의 경우 Azure Functions MCP 확장은 격리된 작업자 모델만 지원합니다.

이 코드는 명명된 코드 조각을 Blob Storage에 유지하려는 명명 SaveSnippet 된 도구를 노출하는 엔드포인트를 만듭니다.

private const string BlobPath = "snippets/{mcptoolargs.snippetname}.json";

[Function(nameof(SaveSnippet))]
[BlobOutput(BlobPath)]
public string SaveSnippet(
    [McpToolTrigger("save_snippet", "Saves a code snippet into your snippet collection.")]
        ToolInvocationContext context,
    [McpToolProperty("snippetname", "The name of the snippet.", isRequired: true)]
        string name,
    [McpToolProperty("snippet", "The code snippet.", isRequired: true)]
        string snippet
)
{
    return snippet;
}

이 코드는 Blob Storage에서 이름으로 코드 조각을 검색하려고 하는 명명된 GetSnippet 도구를 노출하는 엔드포인트를 만듭니다.

private const string BlobPath = "snippets/{mcptoolargs.snippetname}.json";

[Function(nameof(GetSnippet))]
public object GetSnippet(
    [McpToolTrigger("get_snippets", "Gets code snippets from your snippet collection.")]
        ToolInvocationContext context,
    [BlobInput(BlobPath)] string snippetContent
)
{
    return snippetContent;
}

함수의 GetSnippet 도구 속성은 다음에서 구성됩니다.Program.cs

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder
    .ConfigureMcpTool("get_snippets")
    .WithProperty("snippetname", "string", "The name of the snippet.", required: true);

builder.Build().Run();

팁 (조언)

위의 예제에서는 함수의 Program.cs "get_snippets" 도구 이름과 같은 항목에 리터럴 문자열을 사용했습니다. 공유 상수 문자열을 사용하여 프로젝트 전체에서 동기화 상태를 유지하는 것이 좋습니다.

전체 코드 예제는 SnippetTool.cs 참조하세요.

이 코드는 명명된 코드 조각을 Blob Storage에 유지하려는 명명 SaveSnippets 된 도구를 노출하는 엔드포인트를 만듭니다.

@FunctionName("SaveSnippets")
@StorageAccount("AzureWebJobsStorage")
public String saveSnippet(
        @McpToolTrigger(
                name = "saveSnippets",
                description = "Saves a text snippet to your snippets collection."
        )
        String mcpToolInvocationContext,
        @McpToolProperty(
                name = "snippetName",
                propertyType = "string",
                description = "The name of the snippet.",
                required = true
        )
        String snippetName,
        @McpToolProperty(
                name = "snippet",
                propertyType = "string",
                description = "The content of the snippet.",
                required = true
        )
        String snippet,
        @BlobOutput(name = "outputBlob", path = "snippets/{mcptoolargs.snippetName}.json")
        OutputBinding<String> outputBlob,
        final ExecutionContext context
) {
    // Log the entire incoming JSON for debugging
    context.getLogger().info(mcpToolInvocationContext);

    // Log the snippet name and content
    context.getLogger().info("Saving snippet with name: " + snippetName);
    context.getLogger().info("Snippet content:\n" + snippet);

    // Write the snippet content to the output blob
    outputBlob.setValue(snippet);

    return "Successfully saved snippet '" + snippetName + "' with " + snippet.length() + " characters.";
}

이 코드는 Blob Storage에서 이름으로 코드 조각을 검색하려고 하는 명명된 GetSnippets 도구를 노출하는 엔드포인트를 만듭니다.

@FunctionName("GetSnippets")
@StorageAccount("AzureWebJobsStorage")
public String getSnippet(
        @McpToolTrigger(
                name = "getSnippets",
                description = "Gets a text snippet from your snippets collection."
        )
        String mcpToolInvocationContext,
        @McpToolProperty(
                name = "snippetName",
                propertyType = "string",
                description = "The name of the snippet.",
                required = true
        )
        String snippetName,
        @BlobInput(name = "inputBlob", path = "snippets/{mcptoolargs.snippetName}.json")
        String inputBlob,
        final ExecutionContext context
) {
    // Log the entire incoming JSON for debugging
    context.getLogger().info(mcpToolInvocationContext);

    // Log the snippet name and the fetched snippet content from the blob
    context.getLogger().info("Retrieving snippet with name: " + snippetName);
    context.getLogger().info("Snippet content:");
    context.getLogger().info(inputBlob);

    // Return the snippet content or a not found message
    if (inputBlob != null && !inputBlob.trim().isEmpty()) {
        return inputBlob;
    } else {
        return "Snippet '" + snippetName + "' not found.";
    }
}

전체 코드 예제는 Snippets.java 참조하세요.

JavaScript에 대한 예제 코드는 현재 사용할 수 없습니다. Node.js사용하는 일반적인 지침은 TypeScript 예제를 참조하세요.

이 코드는 명명된 코드 조각을 Blob Storage에 유지하려는 명명 savesnippet 된 도구를 노출하는 엔드포인트를 만듭니다.

import { app, InvocationContext, input, output, arg } from "@azure/functions";

app.mcpTool("saveSnippet", {
  toolName: SAVE_SNIPPET_TOOL_NAME,
  description: SAVE_SNIPPET_TOOL_DESCRIPTION,
  toolProperties: {
    [SNIPPET_NAME_PROPERTY_NAME]: arg.string().describe(SNIPPET_NAME_PROPERTY_DESCRIPTION),
    [SNIPPET_PROPERTY_NAME]: arg.string().describe(SNIPPET_PROPERTY_DESCRIPTION)
  },
  extraOutputs: [blobOutputBinding],
  handler: saveSnippet,
});

이 코드는 트리거를 savesnippet 처리합니다.

export async function saveSnippet(
  _toolArguments: unknown,
  context: InvocationContext
): Promise<string> {
  console.info("Saving snippet");

  // Get snippet name and content from the tool arguments
  const mcptoolargs = context.triggerMetadata.mcptoolargs as {
    snippetname?: string;
    snippet?: string;
  };

  const snippetName = mcptoolargs?.snippetname;
  const snippet = mcptoolargs?.snippet;

  if (!snippetName) {
    return "No snippet name provided";
  }

  if (!snippet) {
    return "No snippet content provided";
  }

  // Save the snippet to blob storage using the output binding
  context.extraOutputs.set(blobOutputBinding, snippet);

  console.info(`Saved snippet: ${snippetName}`);
  return snippet;
}

이 코드는 Blob Storage에서 이름으로 코드 조각을 검색하려고 하는 명명된 getsnippet 도구를 노출하는 엔드포인트를 만듭니다.

import { app, InvocationContext, input, output, arg } from "@azure/functions";

app.mcpTool("getSnippet", {
  toolName: GET_SNIPPET_TOOL_NAME,
  description: GET_SNIPPET_TOOL_DESCRIPTION,
  toolProperties: {
    [SNIPPET_NAME_PROPERTY_NAME]: arg.string().describe(SNIPPET_NAME_PROPERTY_DESCRIPTION)
  },
  extraInputs: [blobInputBinding],
  handler: getSnippet,
});

이 코드는 트리거를 getsnippet 처리합니다.

export async function getSnippet(
  _toolArguments: unknown,
  context: InvocationContext
): Promise<string> {
  console.info("Getting snippet");

  // Get snippet name from the tool arguments
  const mcptoolargs = context.triggerMetadata.mcptoolargs as {
    snippetname?: string;
  };
  const snippetName = mcptoolargs?.snippetname;

  console.info(`Snippet name: ${snippetName}`);

  if (!snippetName) {
    return "No snippet name provided";
  }

  // Get the content from blob binding - properly retrieving from extraInputs
  const snippetContent = context.extraInputs.get(blobInputBinding);

  if (!snippetContent) {
    return `Snippet '${snippetName}' not found`;
  }

  console.info(`Retrieved snippet: ${snippetName}`);
  return snippetContent as string;
}

전체 코드 예제는 snippetsMcpTool.ts 참조하세요.

이 코드는 데코레이터를 사용하여 mcp_tool_trigger 엔드포인트를 만들어 명명된 코드 조각을 Blob Storage에 유지하려고 하는 도구를 save_snippet 노출합니다.

@app.mcp_tool_trigger(
    arg_name="context",
    tool_name="save_snippet",
    description="Save a snippet with a name.",
    tool_properties=tool_properties_save_snippets_json,
)
@app.blob_output(arg_name="file", connection="AzureWebJobsStorage", path=_BLOB_PATH)
def save_snippet(file: func.Out[str], context) -> str:
    content = json.loads(context)
    snippet_name_from_args = content["arguments"][_SNIPPET_NAME_PROPERTY_NAME]
    snippet_content_from_args = content["arguments"][_SNIPPET_PROPERTY_NAME]

    if not snippet_name_from_args:
        return "No snippet name provided"

    if not snippet_content_from_args:
        return "No snippet content provided"

    file.set(snippet_content_from_args)
    logging.info(f"Saved snippet: {snippet_content_from_args}")
    return f"Snippet '{snippet_content_from_args}' saved successfully"

이 코드는 mcp_tool_trigger 데코레이터를 사용하여 엔드포인트를 만들어 Blob Storage에서 이름으로 코드 조각을 검색하려고 하는 도구를 get_snippet 노출합니다.

@app.mcp_tool_trigger(
    arg_name="context",
    tool_name="get_snippet",
    description="Retrieve a snippet by name.",
    tool_properties=tool_properties_get_snippets_json,
)
@app.blob_input(arg_name="file", connection="AzureWebJobsStorage", path=_BLOB_PATH)
def get_snippet(file: func.InputStream, context) -> str:
    """
    Retrieves a snippet by name from Azure Blob Storage.

    Args:
        file (func.InputStream): The input binding to read the snippet from Azure Blob Storage.
        context: The trigger context containing the input arguments.

    Returns:
        str: The content of the snippet or an error message.
    """
    snippet_content = file.read().decode("utf-8")
    logging.info(f"Retrieved snippet: {snippet_content}")
    return snippet_content

전체 코드 예제는 function_app.py 참조하세요.

중요합니다

MCP 확장은 현재 PowerShell 앱을 지원하지 않습니다.

특성

C# 라이브러리는 함수 트리거를 정의하는 데 사용합니다 McpToolTriggerAttribute .

특성의 생성자는 다음 매개 변수를 사용합니다.

매개 변수	설명
ToolName	(필수) MCP 트리거 엔드포인트에 의해 노출되는 도구의 이름입니다.
설명	(선택 사항) 클라이언트용 도구 엔드포인트에 대한 친숙한 설명입니다.

엔드포인트의 속성을 입력 매개 변수로 정의하는 방법을 알아보려면 사용법을 참조하세요.

주석

주석은 @McpToolTrigger 원격 MCP 서버에서 도구 엔드포인트를 노출하는 함수를 만듭니다.

주석은 다음 구성 옵션을 지원합니다.

매개 변수	설명
name	(필수) MCP 트리거 엔드포인트에 의해 노출되는 도구의 이름입니다.
묘사	(선택 사항) 클라이언트용 도구 엔드포인트에 대한 친숙한 설명입니다.

주석은 @McpToolProperty 도구에 대한 개별 속성을 정의합니다. 함수의 각 속성 매개 변수는 이 주석으로 주석을 추가해야 합니다.

주석은 @McpToolProperty 다음 구성 옵션을 지원합니다.

매개 변수	설명
name	(필수) 클라이언트에 노출되는 도구 속성의 이름입니다.
propertyType	(필수) 도구 속성의 형식입니다. 유효한 형식은 다음과 stringnumberintegerboolean같습니다. object
묘사	(선택 사항) 도구 속성이 수행하는 작업을 설명합니다.
필수	(선택 사항)로 설정 true하면 도구 속성이 도구 호출의 인수로 필요합니다. 기본값은 false입니다.

장식

Python v2 프로그래밍 모델에만 적용됩니다.

데코레이터에는 mcp_tool_trigger 패키지 버전 1.24.0 이상이 azure-functions필요합니다. 다음 MCP 트리거 속성은 다음에서 지원됩니다.mcp_tool_trigger

재산	설명
arg_name	함수 코드에서 실행 컨텍스트에 액세스하는 데 사용되는 변수 이름(일반적으로 context)입니다.
tool_name	(필수) 함수 엔드포인트에서 노출하는 MCP 서버 도구의 이름입니다.
묘사	함수 엔드포인트에서 노출하는 MCP 서버 도구에 대한 설명입니다.
tool_properties	도구의 속성을 클라이언트에 노출하는 하나 이상의 속성 개체의 JSON 문자열 표현입니다.

구성 / 설정

트리거는 코드에 정의된 다음 바인딩 옵션을 지원합니다.

옵션	설명
유형	mcpToolTrigger로 설정해야 합니다. 제네릭 정의에만 사용됩니다.
toolName	(필수) 함수 엔드포인트에서 노출하는 MCP 서버 도구의 이름입니다.
묘사	함수 엔드포인트에서 노출하는 MCP 서버 도구에 대한 설명입니다.
toolProperties	도구의 toolProperty 속성을 클라이언트에 노출하는 개체의 배열입니다.
extraOutputs	정의되면 함수 출력을 다른 바인딩으로 보냅니다.
처리기	실제 함수 코드를 포함하는 메서드입니다.

전체 예제는 예제 섹션을 참조하세요.

사용법

MCP 도구 트리거는 다음 형식에 바인딩할 수 있습니다.

유형	설명
ToolInvocationContext	호출에 대한 도구 이름 및 인수를 포함하여 도구 호출을 나타내는 개체입니다.
JSON 직렬화 가능 형식	함수는 도구 인수를 POCO(일반 오래된 CLR 개체) 형식으로 역직렬화하려고 시도합니다. 이 형식은 도구 속성을 정의하는 데도 사용됩니다. JSON 직렬화 가능 형식에 바인딩할 때 도구 호출 정보에 액세스하기 위해 ToolInvocationContext 형식의 매개 변수를 선택적으로 포함할 수도 있습니다.

도구 속성

MCP 클라이언트는 인수를 사용하여 도구를 호출하여 도구 작업에 대한 데이터와 컨텍스트를 제공합니다. 클라이언트는 도구가 프로토콜의 일부로 보급하는 속성에 따라 이러한 인수를 수집하고 전달하는 방법을 알고 있습니다. 따라서 함수 코드에서 도구의 속성을 정의해야 합니다.

도구 속성을 정의할 때는 기본적으로 선택 사항이며 클라이언트는 도구를 호출할 때 이를 생략할 수 있습니다. 도구 없이는 작동할 수 없는 경우 속성을 필요에 따라 명시적으로 표시해야 합니다.

비고

이전 버전의 MCP 확장 미리 보기는 기본적으로 필요한 모든 도구 속성을 만들었습니다. 이 동작은 버전 1.0.0-preview.7에서 변경되었으므로 이제 속성을 필요에 따라 명시적으로 표시해야 합니다.

C#에서는 여러 가지 방법으로 도구에 대한 속성을 정의할 수 있습니다. 사용하는 방법은 코드 스타일 기본 설정의 문제입니다. 옵션은 다음과 같습니다.

• 함수는 특성을 사용하여 입력 매개 변수를 McpToolProperty 사용합니다.
• 속성을 사용하여 사용자 지정 형식을 정의하면 함수가 해당 형식에 바인딩됩니다.
• 파일에서 FunctionsApplicationBuilder 속성을 Program.cs 정의하는 데 사용합니다.

McpToolProperty 특성

함수의 입력 바인딩 스타일 매개 변수에 특성을 적용하여 McpToolProperty 하나 이상의 도구 속성을 정의할 수 있습니다.

형식은 McpToolPropertyAttribute 다음 속성을 지원합니다.

재산	설명
PropertyName	클라이언트에 노출되는 도구 속성의 이름입니다.
설명	도구 속성의 용도에 대한 설명입니다.
필수입니다	(선택 사항) 도구 속성으로 true설정하면 도구 호출에 대한 인수로 도구 속성이 필요합니다. 기본값은 false입니다.

속성 형식은 특성을 적용할 매개 변수 형식에서 유추됩니다. 예를 들어 [McpToolProperty("snippetname", "The name of the snippet.", true)] string name MCP 메시지에서 형식 snippetname 이라는 string 필수 도구 속성을 정의합니다.

예제의 SaveSnippet 도구에서 사용되는 이러한 특성을 볼 수 있습니다.

사용자 지정 형식에 바인딩

정의한 POCO(일반 오래된 CLR 개체) 형식에 바인딩하여 하나 이상의 도구 속성을 정의할 수 있습니다. 해당 형식의 속성은 도구 속성으로 자동으로 노출됩니다. [Description] 특성을 사용하여 각 속성에 대한 설명을 제공할 수 있습니다. 키워드를 사용하여 required 속성이 필요함을 나타낼 수 있습니다. MCP 메시지에 사용되는 informs 형식의 클래스 속성 형식입니다.

이 예제에서는 사용자 지정 형식을 사용하여 도구의 도구 속성을 정의합니다 SaveSnippet .

public class SaveSnippetRequest
{
    [Description("The name of the snippet.")]
    public required string SnippetName { get; set; }

    [Description("The code snippet.")]
    public required string Snippet { get; set; }            
}

private const string BlobPath = "snippets/{mcptoolargs.snippetname}.json";

[Function(nameof(SaveSnippet))]
[BlobOutput(BlobPath)]
public string SaveSnippet(
    [McpToolTrigger("save_snippet", "Saves a code snippet into your snippet collection.")] SaveSnippetRequest request,
        ToolInvocationContext context
)
{
    return request.Snippet;
}

FunctionsApplicationBuilder

메서드에서 반환 Program.cs 된 항목을 사용하여 McpToolBuilder 진입점(ConfigureMcpTool()) 파일에서 하나 이상의 도구 속성을 정의할 수 있습니다FunctionsApplicationBuilder. 이 예제에서는 도구에 WithProperty 대한 작성기에서 메서드를 GetSnippet 호출하여 도구의 속성을 설정합니다.

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder
    .ConfigureMcpTool("get_snippets")
    .WithProperty("snippetname", "string", "The name of the snippet.", required: true);

// other configuration

builder.Build().Run();

메서드를 WithProperty() 여러 번 호출하여 도구에 대한 여러 속성을 정의할 수 있습니다. 각 호출 WithProperty() 에는 CLR 형식에 직접 해당하지 않을 수 있는 MCP 속성 형식의 문자열 표현이 포함됩니다. 예를 들어 해당 CLR 형식이 있더라도 부울 속성을 정의하는 데 "boolean"사용합니다bool. 유효한 형식은 다음과 "string""number""integer""boolean"같습니다. "object"

전체 예제는 파일을 참조하세요Program.cs.

Java에서는 개별 함수 매개 변수에 주석을 @McpToolProperty 사용하여 도구 속성을 정의합니다. 도구 속성을 나타내는 각 매개 변수는 속성 이름, 형식, 설명 및 필수 여부를 지정하여 이 주석으로 주석을 추가해야 합니다.

예제에서 사용되는 주석을 볼 수 있습니다.

개체 배열 toolProperties 의 ToolProperty 문자열 표현인 트리거 정의 필드에서 도구 속성을 구성할 수 있습니다.

ToolProperty 개체의 구조는 다음과 같습니다.

{
    "propertyName": "Name of the property",
    "propertyType": "Type of the property",
    "description": "Optional property description",
    "isRequired": true|false,
    "isArray": true|false
}

개체의 ToolProperty 필드는 다음과 같습니다.

재산	설명
propertyName	클라이언트에 노출되는 도구 속성의 이름입니다.
propertyType	도구 속성의 형식입니다. 유효한 형식은 다음과 stringnumberintegerboolean같습니다. object 배열 형식은 참조 isArray 하세요.
묘사	도구 속성의 용도에 대한 설명입니다.
isRequired	(선택 사항) 도구 속성으로 true설정하면 도구 호출에 대한 인수로 도구 속성이 필요합니다. 기본값은 false입니다.
isArray	(선택 사항) 설정된 true경우 도구 속성은 지정된 속성 형식의 배열입니다. 기본값은 false입니다.

필드를 toolProperties 객체 배열 ToolProperty 로 제공할 수도 있고, 도 arg 우미를 @azure/functions 사용해 속성 정의를 보다 타입 안전한 방식으로 할 수도 있습니다:

  toolProperties: {
    [SNIPPET_NAME_PROPERTY_NAME]: arg.string().describe(SNIPPET_NAME_PROPERTY_DESCRIPTION)
  }

자세한 내용은 예제참조하세요.

host.json 설정

host.json 파일에는 MCP 트리거 동작을 제어하는 설정이 포함되어 있습니다. 사용 가능한 설정에 대한 자세한 내용은 host.json 설정 섹션을 참조하세요.

관련 문서

Azure Functions에 대한 Azure OpenAI 확장