Model Context Protocol (MCP)

Connect agents to external systems through the standardized MCP interface.

The Model Context Protocol (MCP) enables Agents to interact with external systems through a standardized interface. You can connect your Agents to any MCP server, using Kern's MCP integration.

Below is a simple example shows how to connect an Agent to the Kern MCP server:

1from kern.agent import Agent
2from kern.models.anthropic import Claude
3from kern.tools.mcp import MCPTools
4
5# Create the Agent
6agno_agent = Agent(
7    name="Kern Agent",
8    model=Claude(id="claude-sonnet-4-0"),
9    # Add the Kern MCP server to the Agent
10    tools=[MCPTools(transport="streamable-http", url="https://kern.ndx.rocks/mcp")],
11)

The Basic Flow

Find the MCP server you want to use

You can use any working MCP server. To see some examples, you can check this GitHub repository, by the maintainers of the MCP themselves.

Initialize the MCP integration

Initialize the MCPTools class and connect to the MCP server. The recommended way to define the MCP server is to use the command or url parameters. With command, you can pass the command used to run the MCP server you want. With url, you can pass the URL of the running MCP server you want to use.

For example, to connect to the Kern documentation MCP server, you can do the following:

1from kern.tools.mcp import MCPTools
2
3# Initialize and connect to the MCP server
4mcp_tools = MCPTools(transport="streamable-http", url="https://kern.ndx.rocks/mcp"))
5await mcp_tools.connect()

Provide the MCPTools to the Agent

When initializing the Agent, pass the MCPTools instance in the tools parameter. Remember to close the connection when you're done.

The agent will now be ready to use the MCP server:

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.tools.mcp import MCPTools
4
5# Initialize and connect to the MCP server
6mcp_tools = MCPTools(url="https://kern.ndx.rocks/mcp")
7await mcp_tools.connect()
8
9try:
10    # Setup and run the agent
11    agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
12    await agent.aprint_response("Tell me more about MCP support in Kern", stream=True)
13finally:
14    # Always close the connection when done
15    await mcp_tools.close()

Example: Filesystem Agent

Here's a filesystem agent that uses the Filesystem MCP server to explore and analyze files:

1import asyncio
2from pathlib import Path
3from textwrap import dedent
4
5from kern.agent import Agent
6from kern.models.openai import OpenAIResponses
7from kern.tools.mcp import MCPTools
8
9
10async def run_agent(message: str) -> None:
11    """Run the filesystem agent with the given message."""
12
13    file_path = "<path to the directory you want to explore>"
14
15    # Initialize and connect to the MCP server to access the filesystem
16    mcp_tools = MCPTools(command=f"npx -y @modelcontextprotocol/server-filesystem {file_path}")
17    await mcp_tools.connect()
18
19    try:
20        agent = Agent(
21            model=OpenAIResponses(id="gpt-5.2"),
22            tools=[mcp_tools],
23            instructions=dedent("""\
24                You are a filesystem assistant. Help users explore files and directories.
25
26                - Navigate the filesystem to answer questions
27                - Use the list_allowed_directories tool to find directories that you can access
28                - Provide clear context about files you examine
29                - Use headings to organize your responses
30                - Be concise and focus on relevant information\
31            """),
32            markdown=True,
33        )
34
35        # Run the agent
36        await agent.aprint_response(message, stream=True)
37    finally:
38        # Always close the connection when done
39        await mcp_tools.close()
40
41
42# Example usage
43if __name__ == "__main__":
44    # Basic example - exploring project license
45    asyncio.run(run_agent("What is the license for this project?"))

Connecting your MCP server

Using `connect()` and `close()`

It is recommended to use the connect() and close() methods to manage the connection lifecycle of the MCP server.

1mcp_tools = MCPTools(command="uvx mcp-server-git")
2await mcp_tools.connect()

After you're done, you should close the connection to the MCP server.

1await mcp_tools.close()

✓

This is the recommended way to manage the connection lifecycle of the MCP server when using Agent or Team instances.

Automatic Connection Management

If you pass the MCPTools instance to the Agent or Team instances without first calling connect(), the connection will be managed automatically.

For example:

1mcp_tools = MCPTools(command="uvx mcp-server-git")
2agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
3await agent.aprint_response("What is the license for this project?", stream=True)  # The connection is established and closed on each run.

Note

Here the connection to the MCP server (in the case of hosted MCP servers) is established and closed on each run. Additionally the list of available tools is refreshed on each run.

This has an impact on performance and is not recommended for production use.

Using Async Context Manager

If you prefer, you can also use MCPTools or MultiMCPTools as async context managers for automatic resource cleanup:

1async with MCPTools(command="uvx mcp-server-git") as mcp_tools:
2    agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
3    await agent.aprint_response("What is the license for this project?", stream=True)

This pattern automatically handles connection and cleanup, but the explicit .connect() and .close() methods provide more control over connection lifecycle.

Automatic Connection Management in AgentOS

When using MCPTools within AgentOS, the lifecycle is automatically managed. No need to manually connect or disconnect the MCPTools instance. This does not automatically refresh connections, you can use refresh_connection to do so.

See the AgentOS + MCPTools page for more details.

✓

This is the recommended way to manage the connection lifecycle of the MCP server when using AgentOS.

Connection Refresh

You can set refresh_connection on the MCPTools and MultiMCPTools instances to refresh the connection to the MCP server on each run.

1mcp_tools = MCPTools(command="uvx mcp-server-git", refresh_connection=True)
2await mcp_tools.connect()
3
4agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
5await agent.aprint_response("What is the license for this project?", stream=True)  # The connection will be refreshed on each run.
6
7await mcp_tools.close()

How it works

When you call the connect() method, a new session is established with the MCP server. If that server becomes unavailable, that connection is closed and a new one has to be established.
If you set refresh_connection to True, each time the agent is run the connection to the MCP server is checked and re-established if needed, and the list of available tools is then refreshed.
This is particularly useful for hosted MCP servers that are prone to restarts or that often change their schema or list of tools.
It is recommended to only use this when you manually manage the connection lifecycle of the MCP server, or when using agents/teams with MCPTools in AgentOS.

Transports

Transports in the Model Context Protocol (MCP) define how messages are sent and received. The Kern integration supports the three existing types:

stdio -> See the stdio transport documentation
Streamable HTTP -> See the streamable HTTP transport documentation
SSE -> See the SSE transport documentation