MCP Integration Examples

These examples show how to connect MCP (Model Context Protocol) servers to your agents using the CAIP Agents SDK.

Framework imports work directly

A key feature of the CAIP Agents SDK is that you do not need to replace your existing framework code. MCP tooling is imported directly from the underlying framework (e.g. pydantic_ai.mcp, langchain_mcp_adapters) and passed straight into the SDK client. The SDK wraps your framework-native objects without any conversion layer — so if you already know PydanticAI, LangChain, or LangGraph, you keep using those APIs as-is.

---

What This Example Demonstrates

• ✅ Connecting a running MCP server to an agent
• ✅ Using framework-native MCP client objects directly with CAIPAgentsClient
• ✅ The same SDK call pattern (create_agent → initialize → create_thread → run) works across all three frameworks
• ✅ How to spin up a minimal local MCP server for testing

---

Prerequisites

• Python 3.12 or 3.13
• CAIP Agent ID (created via CAIP Portal)
• CAIP API Key

CAIP_API_KEY is a unified key for both Agents API and LLM API access. See CAIP API Key Authentication to obtain your key.

export CAIP_API_KEY=your_caip_api_key
export CAIP_AGENT_ID=your_agent_id

---

MCP Server (Local Example)

Before running any of the agent examples below you need a running MCP server. The following minimal server exposes a single add tool over the streamable-http transport on port 8001.

mcp_server.py

from mcp.server.fastmcp import FastMCP

app = FastMCP(port=8001)


@app.tool()
def add(a: int, b: int) -> int:
    print("Adding", a, "and", b)
    return a + b


if __name__ == "__main__":
    app.run(transport="streamable-http")

Start it in a separate terminal:

python mcp_server.py

---

Agent Examples

The tabs below show how to connect the same MCP server using PydanticAI, LangChain, and LangGraph. In each case the MCP client object comes from the framework's own package and is passed directly to client.create_agent(...).

PydanticAI

MCPToolset is imported directly from pydantic_ai.mcp — no adapter or wrapper from the SDK is needed.

pydantic_ai_mcp.py

from caip_agents_sdk import CAIPAgentsClient
import asyncio, os
from pydantic_ai.mcp import MCPToolset


async def main():
    # Initialize client
    client = CAIPAgentsClient()

    AGENT_ID = os.getenv("CAIP_AGENT_ID")
    toolset = MCPToolset("http://localhost:8001/mcp")

    agent = client.create_agent(
        framework="pydantic_ai", agent_id=AGENT_ID, toolsets=[toolset]
    )

    await agent.initialize()
    thread = await client.create_thread(
        agent_id=AGENT_ID,
        thread_data={"title": "Hello World", "status": "open"},
    )
    agent.thread_id = thread.threadId

    result = await agent.run("What is 7 plus 5?")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

Install dependencies:

pip install caip-agents-sdk pydantic-ai

LangChain

MultiServerMCPClient is imported from langchain_mcp_adapters — the standard LangChain MCP adapter package. Pass the resolved tools directly to create_agent.

langchain_mcp.py

from langchain_mcp_adapters.client import MultiServerMCPClient
from caip_agents_sdk import CAIPAgentsClient
import asyncio, os


async def main():
    # Initialize client
    client = CAIPAgentsClient()

    AGENT_ID = os.getenv("CAIP_AGENT_ID")
    mcp_client = MultiServerMCPClient(
        {
            "mcp": {
                "transport": "http",
                "url": "http://localhost:8001/mcp",  # Local server
                # "url": "https://docs.langchain.com/mcp",  # Hosted server
            }
        }
    )
    tools = await mcp_client.get_tools()
    agent = client.create_agent(framework="langchain", agent_id=AGENT_ID, tools=tools)

    await agent.initialize()
    thread = await client.create_thread(
        agent_id=AGENT_ID,
        thread_data={"title": "Hello World", "status": "open"},
    )
    agent.thread_id = thread.threadId

    result = await agent.run("What is 7 plus 5?")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

Install dependencies:

pip install caip-agents-sdk langchain-mcp-adapters

LangGraph

LangGraph uses the same langchain_mcp_adapters client as LangChain. The only difference is framework="langgraph" in create_agent.

langgraph_mcp.py

from langchain_mcp_adapters.client import MultiServerMCPClient
from caip_agents_sdk import CAIPAgentsClient
import asyncio, os


async def main():
    # Initialize client
    client = CAIPAgentsClient()

    AGENT_ID = os.getenv("CAIP_AGENT_ID")
    mcp_client = MultiServerMCPClient(
        {
            "mcp": {
                "transport": "http",
                "url": "http://localhost:8001/mcp",  # Local server
                # "url": "https://docs.langchain.com/mcp",  # Hosted server
            }
        }
    )
    tools = await mcp_client.get_tools()
    agent = client.create_agent(framework="langgraph", agent_id=AGENT_ID, tools=tools)

    await agent.initialize()
    thread = await client.create_thread(
        agent_id=AGENT_ID,
        thread_data={"title": "Hello World", "status": "open"},
    )
    agent.thread_id = thread.threadId

    result = await agent.run("What is 7 plus 5?")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())

Install dependencies:

pip install caip-agents-sdk langchain-mcp-adapters

---

How It Works

The CAIP Agents SDK does not own the MCP connection — the framework does. The SDK's role is to:

1. Accept the framework-native toolset or tool list you already built
2. Wrap the agent in the CAIP lifecycle (thread management, message persistence, API routing)
3. Run the agent through the same agent.run(...) interface regardless of framework

This means you can adopt the SDK incrementally: start with the framework you already know, add MCP tools the way that framework expects, and let the SDK handle the CAIP-specific infrastructure around it.

Framework	MCP import	create_agent key
PydanticAI	pydantic_ai.mcp.MCPToolset	toolsets=[...]
LangChain	langchain_mcp_adapters.client.MultiServerMCPClient	tools=[...]
LangGraph	langchain_mcp_adapters.client.MultiServerMCPClient	tools=[...]