> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Model Context Protocol
description: Connect external MCP servers to AGNT5 agents, or expose AGNT5 tools and agents over a local MCP server.
last_verified: 2026-06-12
---

**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.

```python
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:

```python
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:

```python
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:

```typescript
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:

```python
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:

```python
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 |

<Callout type="info">Always call `connect()` first. The tool list is built from the cache populated during connection.</Callout>

## 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.

```python
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:

```python
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](/docs/build/tools.md): define AGNT5 tools that agents and MCP clients can call.
- [Agents](/docs/build/agents.md): attach imported MCP tools to an agent loop.
- [AI providers](/docs/integrations/ai-providers.md): configure model credentials for agents that use MCP tools.
- [Local development](/docs/build/local-development.md): run and test AGNT5 code from your laptop.