Semantic Kernel MCP Tutorial: MCP Plugins in Python, and the Move to Agent Framework

Semantic Kernel treats an MCP server as a plugin. You open an MCPStreamableHttpPlugin or MCPStdioPlugin, add it to a kernel or agent, and the server's tools become kernel functions the model can call. The server's prompts load too.

There is an important twist in 2026. The Semantic Kernel README now says "Semantic Kernel is now Microsoft Agent Framework" and calls Agent Framework "the enterprise-ready successor." This tutorial shows the Semantic Kernel MCP code that existing projects use, then the equivalent Agent Framework code for new ones. Code was checked against Microsoft's Semantic Kernel MCP page, the SK Python source and samples, and the Agent Framework MCP tools page on 2 November 2026. PyPI listed semantic-kernel 1.46.0 and agent-framework 1.24.0 that day.

Prerequisites

• Python 3.10 or later.
• An Azure OpenAI or OpenAI deployment for the agent's model.
• Node.js, Docker or uvx if you want to run community MCP servers locally.

Install

pip install "semantic-kernel[mcp]"

The version pin

On PyPI, semantic-kernel 1.46.0 requires mcp>=1.26.0,<2.0. The official MCP Python SDK is now on v2, and Agent Framework requires v2. You cannot install both frameworks' MCP support in one virtual environment. Keep them separate, and run any MCP server you write in its own environment too.

Minimal working example (Streamable HTTP)

This follows the SK sample agent_with_http_mcp_plugin.py. It connects to Microsoft Learn's public docs MCP server and asks a question:

import asyncio

from azure.identity import AzureCliCredential
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.connectors.mcp import MCPStreamableHttpPlugin


async def main():
    async with MCPStreamableHttpPlugin(
        name="LearnSite",
        description="Learn Docs Plugin",
        url="https://learn.microsoft.com/api/mcp",
    ) as learn_plugin:
        agent = ChatCompletionAgent(
            service=AzureChatCompletion(credential=AzureCliCredential()),
            name="DocsAgent",
            instructions="Answer questions about Microsoft's Semantic Kernel SDK.",
            plugins=[learn_plugin],
        )
        response = await agent.get_response(
            messages="How do I make a Python chat completion request in Semantic Kernel?"
        )
        print(response)


asyncio.run(main())

The sample expects AZURE_OPENAI_CHAT_DEPLOYMENT_NAME to be set. To use OpenAI directly, swap in the OpenAI chat completion service from the same connector module.

The async with block opens the connection and closes it. You can also call await plugin.connect() and await plugin.close() yourself.

Local servers over stdio

Microsoft's page shows how a typical desktop-app config maps to MCPStdioPlugin. A GitHub server run in Docker becomes:

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)
        # use the kernel or pass the plugin to an agent

Give the token the narrowest scopes that work. Our GitHub MCP server profile lists which tools write to your repositories.

Plugin options

All SK MCP plugins accept:

• load_tools: load the server's tools (default True).
• load_prompts: load the server's prompts (default True). Microsoft's page says they "have also heard cases where the call to load prompts hangs" on servers with no prompts, so set False when you know there are none.
• request_timeout: stop your app hanging on an unresponsive server.

MCPStreamableHttpPlugin also takes headers for auth, plus timeout and sse_read_timeout. The SK source shows sampling options too (sampling_consent_callback and sampling_auto_approve, which defaults to False). Leave auto-approve off unless you trust the server.

There are also MCPSsePlugin and MCPWebsocketPlugin classes. SSE is a deprecated MCP transport; prefer Streamable HTTP. See SSE vs Streamable HTTP.

Add a tool

With an MCP plugin, tools come from the server. Add a tool there, restart it, and reopen the plugin. Each tool becomes a function inside the plugin named by name=, so pick short plugin names the model can read.

Expose a kernel as an MCP server

The SK Python package also goes the other way. Its semantic_kernel.connectors.mcp module contains create_mcp_server_from_kernel and create_mcp_server_from_functions, and the SK repo's demos/mcp_server folder shows a complete server. Because SK pins mcp<2, those servers run on MCP Python SDK v1.

Test with the MCP Inspector

Test any HTTP server without a model in the loop:

npx @modelcontextprotocol/inspector --cli https://learn.microsoft.com/api/mcp --transport http --method tools/list

Then add the plugin to your agent. Our MCP Inspector lesson covers tool calls and scripted checks.

The Agent Framework version

Microsoft's Agent Framework MCP page shows the same idea with new names. On minimal installs it says to install mcp>=2.2.0,<3.

import asyncio

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential


async def http_mcp_example():
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        async with (
            MCPStreamableHTTPTool(
                name="Microsoft Learn MCP",
                url="https://learn.microsoft.com/api/mcp",
            ) as mcp_server,
            Agent(
                client=client,
                name="DocsAgent",
                instructions="You help with Microsoft documentation questions.",
            ) as agent,
        ):
            result = await agent.run(
                "How to create an Azure storage account using az cli?",
                tools=mcp_server,
            )
            print(result)


asyncio.run(http_mcp_example())

A local stdio server looks like this in Agent Framework, from the same page:

import asyncio

from agent_framework import Agent, MCPStdioTool
from agent_framework.openai import OpenAIChatClient


async def local_mcp_example():
    async with (
        MCPStdioTool(
            name="calculator",
            command="uvx",
            args=["mcp-server-calculator"]
        ) as mcp_server,
        Agent(
            client=OpenAIChatClient(),
            name="MathAgent",
            instructions="You are a helpful math assistant that can solve calculations.",
        ) as agent,
    ):
        result = await agent.run("What is 15 * 23 + 45?", tools=mcp_server)
        print(result)


asyncio.run(local_mcp_example())

Passing command= or url= creates what Microsoft calls a "framework-owned" client: Agent Framework enters, reconnects and closes it. If you need to configure the client yourself, open an mcp.Client first and pass it with mcp_client=. Microsoft says caller-supplied low-level ClientSession objects "remain a deprecated compatibility path."

Mapping the concepts:

Agent Framework adds controls Semantic Kernel lacks: static_headers for fixed credentials, a header_provider for per-run values, and headers stripped on cross-origin redirects. Microsoft publishes a migration guide from Semantic Kernel.

Which one should you use?

• You have a Semantic Kernel app in production. Keep the MCP plugins. They work, and the package is still published. Plan the move to Agent Framework on your own schedule, using Microsoft's migration guide.
• You are starting a new agent project. Start on Agent Framework. It is the successor, it uses the current MCP Python SDK, and its MCP docs cover Python, C# and Go.
• You need C# today. Semantic Kernel's MCP page has no .NET content yet, while Agent Framework documents C# MCP tools and exposing an agent as an MCP server.
• You need per-user credentials. Agent Framework's header_provider builds headers per run. With Semantic Kernel, you would open a separate plugin per user.

Pitfalls

• Mixing SK and Agent Framework in one env. The mcp pins conflict.
• Hanging on prompt loading. Set load_prompts=False for tool-only servers.
• Copy-paste bug in Microsoft's manual-connect sample. It creates plugin but adds github_plugin. Use the same variable name in both lines.
• Unscoped tokens. A plugin can call every tool the server exposes. Scope credentials on the server side, and read permissions and approvals.

Next step

If you are choosing a stack, our free MCP course explains what any framework's MCP layer needs to do. If you want MCP servers built for a Microsoft-based agent stack, see our MCP development service.

Frequently asked questions