Merge pull request #532 from MicrosoftDocs/main

added MCP docs

Author: sophialagerkranspandey

semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md

@@ -214,6 +214,7 @@ When using auto function calling in KernelFunctions, certain parameter names are
 ### Reserved Names
 
 The following parameter names are reserved:
+
 - `kernel`
 - `service`
 - `execution_settings`
@@ -242,6 +243,37 @@ class SimplePlugin:
         return f"Received user input: {location}, the weather is nice!"
 ```
 
+## Custom Reserved Parameter Names for Auto Function Calling
+
+You can also customize this behavior. In order to do that, you need to annotate the parameter you want to exclude from the function calling definition, like this:
+
+```python
+class SimplePlugin:
+    @kernel_function(name="GetWeather", description="Get the weather for a location.")
+    async def get_the_weather(self, location: str, special_arg: Annotated[str, {"include_in_function_choices": False}]) -> str:
+        # The 'special_arg' parameter is reserved and you need to ensure it either has a default value or gets passed.
+```
+
+When calling this function, make sure to pass the `special_arg` parameter, otherwise it will raise an error.
+
+```python
+response = await kernel.invoke_async(
+    plugin_name=...,
+    function_name="GetWeather",
+    location="Seattle",
+    special_arg="This is a special argument"
+)
+```
+
+Or add it to the `KernelArguments` object to use it with auto function calling in an agent like this:
+
+```python
+arguments = KernelArguments(special_arg="This is a special argument")
+response = await agent.get_response(
+    messages="what's the weather in Seattle?"
+    arguments=arguments)
+```
+
 ::: zone-end
 
 ::: zone pivot="programming-language-java"

semantic-kernel/concepts/kernel.md

@@ -14,11 +14,13 @@ ms.service: semantic-kernel
 The kernel is the central component of Semantic Kernel. At its simplest, the kernel is a Dependency Injection container that manages all of the services and plugins necessary to run your AI application. If you provide all of your services and plugins to the kernel, they will then be seamlessly used by the AI as needed.
 
 ## The kernel is at the center
+
 Because the kernel has all of the services and plugins necessary to run both native code and AI services, it is used by nearly every component within the Semantic Kernel SDK to power your agents. This means that if you run any prompt or code in Semantic Kernel, the kernel will always be available to retrieve the necessary services and plugins.
 
 ![The kernel is at the center of everything in Semantic Kernel](../media/the-kernel-is-at-the-center-of-everything.png)
 
 This is extremely powerful, because it means you as a developer have a single place where you can configure, and most importantly monitor, your AI agents. Take for example, when you invoke a prompt from the kernel. When you do so, the kernel will...
+
 1. Select the best AI service to run the prompt.
 2. Build the prompt using the provided prompt template.
 3. Send the prompt to the AI service.
@@ -28,12 +30,13 @@ This is extremely powerful, because it means you as a developer have a single pl
 Throughout this entire process, you can create events and middleware that are triggered at each of these steps. This means you can perform actions like logging, provide status updates to users, and most importantly responsible AI. All from a single place.
 
 ## Build a kernel with services and plugins
+
 Before building a kernel, you should first understand the two types of components that exist:
 
-| | Components | Description |
-|---|---|---|
-| 1 | **Services** | These consist of both AI services (e.g., chat completion) and other services (e.g., logging and HTTP clients) that are necessary to run your application. This was modelled after the Service Provider pattern in .NET so that we could support dependency injection across all languages. |
-| 2 | **Plugins** | These are the components that are used by your AI services and prompt templates to perform work. AI services, for example, can use plugins to retrieve data from a database or call an external API to perform actions. |
+| Component | Description |
+|---|---|
+| **Services** | These consist of both AI services (e.g., chat completion) and other services (e.g., logging and HTTP clients) that are necessary to run your application. This was modelled after the Service Provider pattern in .NET so that we could support dependency injection across all languages. |
+| **Plugins** | These are the components that are used by your AI services and prompt templates to perform work. AI services, for example, can use plugins to retrieve data from a database or call an external API to perform actions. |
 
 ::: zone pivot="programming-language-csharp"
 To start creating a kernel, import the necessary packages at the top of your file:
@@ -49,7 +52,7 @@ builder.AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);
 builder.Services.AddLogging(c => c.AddDebug().SetMinimumLevel(LogLevel.Trace));
 builder.Plugins.AddFromType<TimePlugin>();
 Kernel kernel = builder.Build();
-``` 
+```
 
 ::: zone-end
 
@@ -82,6 +85,119 @@ kernel.add_plugin(
 )
 ```
 
+## Creating a MCP Server from your Kernel
+
+We now support creating a MCP server from the function you have registered in your Semantic Kernel instance.
+
+In order to do this, you create your kernel as you normally would, and then you can create a MCP server from it.
+
+```python
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
+from semantic_kernel.functions import kernel_function
+from semantic_kernel.prompt_template import InputVariable, PromptTemplateConfig
+
+kernel = Kernel()
+
+@kernel_function()
+def echo_function(message: str, extra: str = "") -> str:
+    """Echo a message as a function"""
+    return f"Function echo: {message} {extra}"
+
+kernel.add_service(OpenAIChatCompletion(service_id="default"))
+kernel.add_function("echo", echo_function, "echo_function")
+kernel.add_function(
+    plugin_name="prompt",
+    function_name="prompt",
+    prompt_template_config=PromptTemplateConfig(
+        name="prompt",
+        description="This is a prompt",
+        template="Please repeat this: {{$message}} and this: {{$extra}}",
+        input_variables=[
+            InputVariable(
+                name="message",
+                description="This is the message.",
+                is_required=True,
+                json_schema='{ "type": "string", "description": "This is the message."}',
+            ),
+            InputVariable(
+                name="extra",
+                description="This is extra.",
+                default="default",
+                is_required=False,
+                json_schema='{ "type": "string", "description": "This is the message."}',
+            ),
+        ],
+    ),
+)
+server = kernel.as_mcp_server(server_name="sk")
+
+```
+
+The `server` object created above comes from the mcp package, you can extend it even further for instance by adding resources, or other features to it. And then you can bring it online, for instance to be used with Stdio:
+
+```python
+import anyio
+from mcp.server.stdio import stdio_server
+
+async def handle_stdin(stdin: Any | None = None, stdout: Any | None = None) -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+anyio.run(handle_stdin)
+```
+
+Or with SSE:
+
+```python
+import uvicorn
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.routing import Mount, Route
+
+sse = SseServerTransport("/messages/")
+
+async def handle_sse(request):
+    async with sse.connect_sse(request.scope, request.receive, request._send) as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+starlette_app = Starlette(
+    debug=True,
+    routes=[
+        Route("/sse", endpoint=handle_sse),
+        Mount("/messages/", app=sse.handle_post_message),
+    ],
+)
+
+uvicorn.run(starlette_app, host="0.0.0.0", port=8000)
+```
+
+### Exposing prompt templates as MCP Prompt
+
+You can also leverage the different Semantic Kernel prompt templates by exposing them as MCP Prompts, like this:
+
+```python
+from semantic_kernel.prompt_template import InputVariable, KernelPromptTemplate, PromptTemplateConfig
+
+prompt = KernelPromptTemplate(
+    prompt_template_config=PromptTemplateConfig(
+        name="release_notes_prompt",
+        description="This creates the prompts for a full set of release notes based on the PR messages given.",
+        template=template,
+        input_variables=[
+            InputVariable(
+                name="messages",
+                description="These are the PR messages, they are a single string with new lines.",
+                is_required=True,
+                json_schema='{"type": "string"}',
+            )
+        ],
+    )
+)
+
+server = kernel.as_mcp_server(server_name="sk_release_notes", prompts=[prompt])
+```
+
 ::: zone-end
 
 ::: zone pivot="programming-language-java"
@@ -99,8 +215,8 @@ Kernel kernel = Kernel.builder()
 
 ::: zone-end
 
-
 ::: zone pivot="programming-language-csharp"
+
 ## Using Dependency Injection
 
 In C#, you can use Dependency Injection to create a kernel. This is done by creating a `ServiceCollection` and adding services and plugins to it. Below is an example of how you can create a kernel using Dependency Injection.
@@ -151,6 +267,7 @@ builder.Services.AddTransient((serviceProvider)=> {
 ::: zone-end
 
 ## Next steps
+
 Now that you understand the kernel, you can learn about all the different AI services that you can add to it.
 
 > [!div class="nextstepaction"]

semantic-kernel/concepts/plugins/TOC.yml

@@ -4,6 +4,8 @@
   href: adding-native-plugins.md
 - name: Adding OpenAPI plugins
   href: adding-openapi-plugins.md
+- name: Adding MCP plugins
+  href: adding-mcp-plugins.md
 - name: Adding Logic Apps as plugins
   href: adding-logic-apps-as-plugins.md
 - name: Using data retrieval functions for RAG

semantic-kernel/concepts/plugins/adding-mcp-plugins.md

@@ -0,0 +1,118 @@
+---
+title: Give agents access to MCP Servers
+description: Learn how to add plugins from a MCP Server to your agents in Semantic Kernel.
+zone_pivot_groups: programming-languages
+author: eavanvalkenburg
+ms.topic: conceptual
+ms.author: edvan
+ms.date: 04/15/2025
+ms.service: semantic-kernel
+---
+
+# Add plugins from a MCP Server
+
+MCP is the Model Context Protocol, it is an open protocol that is designed to allow additional capabilities to be added to AI applications with ease, see [the documentation](https://modelcontextprotocol.io/introduction) for more info.
+Semantic Kernel allows you to add plugins from a MCP Server to your agents. This is useful when you want to use plugins that are made available as a MCP Server.
+
+Semantic Kernel supports both local MCP Servers, through Stdio, or servers that connect through SSE over HTTPS.
+
+## Add plugins from a local MCP Server
+
+To add a locally running MCP server, you can use the familiar MCP commands, like `npx`, `docker` or `uvx`, so if you want to run one of those, make sure those are installed.
+
+For instance when you look into your claude desktop config, or the vscode settings.json, you would see something like this:
+
+```json
+{
+    "mcpServers": {
+        "github": {
+           "command": "docker",
+           "args": [
+                 "run",
+                 "-i",
+                 "--rm",
+                 "-e",
+                 "GITHUB_PERSONAL_ACCESS_TOKEN",
+                 "ghcr.io/github/github-mcp-server"
+           ],
+           "env": {
+                 "GITHUB_PERSONAL_ACCESS_TOKEN": "..."
+           }
+        }
+    }
+}
+```
+
+In order to make the same plugin available to your kernel or agent, you would do this:
+
+::: zone pivot="programming-language-python"
+
+```python
+import os
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.mcp import MCPStdioPlugin
+
+async def main():
+    async with MCPStdioPlugin(
+        name="Github",
+        description="Github Plugin",
+        command="docker",
+        args=["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+        env={"GITHUB_PERSONAL_ACCESS_TOKEN": os.getenv("GITHUB_PERSONAL_ACCESS_TOKEN")},
+    ) as github_plugin:
+        kernel = Kernel()
+        kernel.add_plugin(github_plugin)
+        # Do something with the kernel
+```
+
+An SSE-based MCP server is even simpler as it just needs the URL:
+
+```python
+import os
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.mcp import MCPSsePlugin
+
+async def main():
+    async with MCPSsePlugin(
+        name="Github",
+        description="Github Plugin",
+        url="http://localhost:8080",
+    ) as github_plugin:
+        kernel = Kernel()
+        kernel.add_plugin(github_plugin)
+        # Do something with the kernel
+```
+
+In both case the async context manager is used to setup the connection and close it, you can also do this manually:
+
+```python
+import os
+from semantic_kernel import Kernel
+from semantic_kernel.connectors.mcp import MCPSsePlugin
+
+async def main():
+    plugin = MCPSsePlugin(
+        name="Github",
+        description="Github Plugin",
+        url="http://localhost:8080",
+    )
+    await plugin.connect()   
+    kernel = Kernel()
+    kernel.add_plugin(github_plugin)
+    # Do something with the kernel
+    await plugin.close()
+```
+
+::: zone-end
+::: zone pivot="programming-language-csharp"
+
+> [!NOTE]
+> MCP Documentation is coming soon for .Net.
+
+::: zone-end
+::: zone pivot="programming-language-java"
+
+> [!NOTE]
+> MCP Documentation is coming soon for Java.
+
+::: zone-end