---

name: mcp-and-integrations description: "Guides agents that connect Pydantic AI agents to MCP, FastMCP, A2A, durable execution, capabilities, hooks, Logfire, AG-UI, Vercel AI, and web integration surfaces." disable-model-invocation: true metadata: disco-role: operating license: MIT

MCP and Integrations

Use this sub-skill when a task connects Pydantic AI agents to external protocols, application runtimes, observability, durable workflow engines, UI adapters, or capability-driven integration bundles rather than defining ordinary Python function tools.

Read First

• Read references/mcp-workflows.md to choose between MCPToolset, legacy MCPServer*, MCP capability native/local selection, FastMCP inputs, agent-inside-MCP-server recipes, resource/prompt access, sampling, and MCP lifecycle management.
• Read references/capabilities-and-hooks.md when packaging integrations as Capability, Hooks, NativeOrLocalTool, WebSearch, WebFetch, Instrumentation, or deferred/on-demand workflows with stable capability IDs.
• Read references/durable-and-ui-integrations.md when wrapping agents for Temporal, Prefect, DBOS, Restate/Kitaru-style durable systems, A2A servers, AGUIAdapter, VercelAIAdapter, to_web(), or web UI embedding.
• Read references/troubleshooting.md to debug optional extras, MCP native-vs-local confusion, capability resume state, hook ordering, Logfire/OTel setup, durable backend services, UI adapter message limits, and credential-bound integrations.
• Run scripts/integration_import_check.py for no-network import and signature diagnostics for optional integration groups before claiming local support for MCP, FastMCP, A2A, Logfire, AG-UI, Vercel AI, durable engines, or web extras.

Route Elsewhere

• Use ../agent-core/SKILL.md for basic Agent construction, run methods, AgentSpec, dependencies, streaming, testing, and message-history continuation.
• Use ../tools-and-toolsets/SKILL.md for individual Python function tools, FunctionToolset, generic wrapper toolsets, approvals, deferred tool mechanics, and tool schema debugging.
• Use ../models-and-providers/SKILL.md for provider-specific model strings, provider SDK installation, native provider tools that are not MCP-specific, embeddings, fallback models, and provider credentials.
• Use ../outputs-and-messages/SKILL.md for structured output design, message serialization, multimodal content model details, and UI message persistence that is not adapter-specific.
• Use ../cli-and-apps/SKILL.md for pai, clai, clai web, command-line flags, and app-launch instructions.

Decision Guide

• Prefer pydantic_ai.mcp.MCPToolset for MCP clients; it is the current full-protocol path built on FastMCP Client and accepts URLs, script paths, transports, in-process FastMCP servers, pre-built clients, and multi-server config via load_mcp_toolsets().
• Use pydantic_ai.capabilities.MCP when a remote MCP server may be provider-native on models that support native MCP, with a local MCPToolset fallback where the mcp extra is installed.
• Treat MCPServerStdio, MCPServerSSE, MCPServerHTTP, MCPServerStreamableHTTP, load_mcp_servers(), and FastMCPToolset as compatibility/deprecation surfaces; document migration toward MCPToolset in new guidance.
• Use Capability or a custom AbstractCapability when an integration owns instructions, tools/toolsets, native tools, settings, lifecycle hooks, event/history processing, or deferred loading as one unit.
• Use durable wrappers only when the backend service/runtime is part of the deployment plan; keep model, toolset, MCP, and capability IDs stable before wrapping.
• Use UI adapters for protocol translation and streaming responses, not as a replacement for application authorization, input sanitization, persistence, or provider credential management.

Safety Defaults

• Do not start MCP servers, ASGI apps, durable workers, browser UIs, or network clients during skill diagnostics unless the user explicitly asks and required services are available.
• Never print API keys, authorization headers, OAuth tokens, backend connection strings, or provider credentials; diagnostic scripts should report only import presence and variable names.
• For local MCP stdio commands, pass explicit env= values and a deliberate cwd= rather than inheriting the whole process environment by default.
• For deferred capabilities, always set stable explicit id values before persisting or replaying message history.
• For UI adapters, keep manage_system_prompt='server', HTTP(S)-only file URLs, and preserve_file_data=False unless the frontend is trusted and audited.