Model Context Protocol

Connect external MCP servers to AGNT5 agents, or expose AGNT5 tools and agents over a local MCP server.

Model Context Protocol (MCP) is an open standard for connecting AI systems to external tools and data sources. AGNT5 supports it in both directions:

MCPClient pulls tools from any external MCP server into your agents.
MCPServer publishes your AGNT5 tools, agents, workflows, and prompts so any MCP-compatible client can call them.

Connect external MCP servers

MCPClient connects to one or more MCP servers, discovers their tools, and converts those tools into AGNT5 Tool objects.

from agnt5 import Agent
from agnt5.mcp import MCPClient

mcp = MCPClient(id="deepwiki-client")
mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")
await mcp.connect()

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="Use available tools to answer questions about code repositories.",
    tools=mcp.get_tools(),
)

result = await agent.run("What is CPython and what is it written in?")
print(result.output)

await mcp.disconnect()

Use async with when you want the client to connect and disconnect around one block:

from agnt5 import Agent
from agnt5.mcp import MCPClient

mcp = MCPClient(id="deepwiki-client")
mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")

async with mcp:
    agent = Agent(
        name="researcher",
        model="openai/gpt-4o-mini",
        instructions="Use available tools to answer questions about code repositories.",
        tools=mcp.get_tools(),
    )
    result = await agent.run("What is CPython and what is it written in?")
    print(result.output)

Client transports

A client transport defines how AGNT5 connects to an MCP server.

Transport	Use it for	Python	TypeScript
stdio	Local servers launched as a subprocess	Available	Available
Streamable HTTP	Current-spec remote MCP servers over HTTP streaming	Available	Available
SSE	Legacy remote servers over Server-Sent Events	Available	Available

Configure servers with the typed helpers:

from agnt5.mcp import MCPClient

mcp = MCPClient(id="tools")

mcp.add_streamable_http_server("deepwiki", "https://mcp.deepwiki.com/mcp")
mcp.add_sse_server("internal-tools", url="https://example.com/sse", api_key="...")
mcp.add_stdio_server("local", command="npx", args=["-y", "my-mcp-server"])

TypeScript uses camelCase helper names:

import { MCPClient } from "@agnt5/sdk";

const mcp = new MCPClient("tools");

mcp.addStreamableHttpServer("deepwiki", "https://mcp.deepwiki.com/mcp");
mcp.addSseServer("internal-tools", "https://example.com/sse", {
  Authorization: "Bearer ...",
});
mcp.addStdioServer("local", "npx", ["-y", "my-mcp-server"]);

Work with MCP tools

After connect(), the client caches discovered tools. Call a tool directly when you know the server name:

result = await mcp.call_tool("deepwiki", "ask_question", {
    "repoName": "python/cpython",
    "question": "What is CPython?",
})

print(result.get_text())

Call by tool name when the server does not matter:

result = await mcp.call_tool_auto("ask_question", {
    "repoName": "python/cpython",
    "question": "What language is CPython written in?",
})

print(result.get_text())

Common client methods:

Method	What it does
`connect()` / `disconnect()`	Open and close connections to all configured servers
`get_tools()`	Return discovered MCP tools as AGNT5 `Tool` objects for `Agent(tools=...)`
`list_tools()`	List every discovered tool with its source server
`list_server_tools(server)`	List tools from one server
`call_tool(server, name, args)`	Call a tool on a specific server
`call_tool_auto(name, args)`	Call the first matching tool name across connected servers
`is_connected(server)`	Check whether one server is connected
`connected_servers()`	Return connected server names

Always call connect() first. The tool list is built from the cache populated during connection.

Expose AGNT5 over MCP

MCPServer runs the protocol in reverse: it publishes AGNT5 primitives so MCP-compatible clients can call them. Use stdio for local developer workflows in Claude Desktop, Cursor, VS Code, and similar clients. Use Streamable HTTP when you want to host the server behind an HTTP endpoint.

from agnt5 import Agent
from agnt5.mcp import MCPServer
from agnt5.tool import tool

@tool
async def greet(ctx, name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

assistant = Agent(
    name="assistant",
    model="openai/gpt-4o-mini",
    instructions="Help the user.",
)

server = MCPServer(
    id="my-server",
    name="My AGNT5 Server",
    version="1.0.0",
    tools={"greet": greet},
    agents={"assistant": assistant},
)

await server.run_stdio()

You can register primitives when constructing the server or add them later:

server.add_tool("search", search_tool)
server.add_agent("analyst", analyst_agent)
server.add_workflow("pipeline", my_workflow)

Server transports

Method	Python	TypeScript
`run_stdio()` / `runStdio()`	Available	Available
`run_http(host, port, path)` / `runHTTP()`	Available	Available

Server-side legacy SSE hosting is not exposed. Current MCP remote hosting should use Streamable HTTP.

Next steps

Tools: define AGNT5 tools that agents and MCP clients can call.
Agents: attach imported MCP tools to an agent loop.
AI providers: configure model credentials for agents that use MCP tools.
Local development: run and test AGNT5 code from your laptop.