MCP with fast-agent

fast-agent provides comprehensive MCP support as both Clients and Server:

• Client: connect agents to local or remote MCP servers.
• Server: expose fast-agent agents, AgentCards, and Harness apps as MCP servers with FastMCP.
• Protocol features: work with MCP types, resources, elicitations, state transfer, OAuth, UI content, and MCP Apps.

Choose your path

Deployment modes

We use these names throughout the MCP docs:

--transport http and --transport stdio choose the wire transport for managed MCP server mode. They are not separate deployment modes. Session scope (request, connection, or legacy shared) is a separate choice.

The two adapter modes both use HarnessMCPAdapter; they differ only in the FastMCP surface. Custom tool adapter mode uses ordinary @mcp.tool() handlers. MCP Apps adapter mode uses FastMCPApp.ui() and FastMCPApp.tool() handlers so FastMCP can serve UI resources, app metadata, CSP, permissions, and app-only backend tools.

Integration with MCP Types

fast-agent uses MCP protocol types throughout the runtime, so MCP content can move between servers, agents, workflows, and protocol adapters without being flattened to plain strings too early.

Conversations are based on PromptMessageExtended, fast-agent's extension of the MCP PromptMessage type. It supports multiple content sections and is used for:

• normal chat turns;
• MCP tool results and resource content;
• history transfer between agents;
• Harness API AgentRequest / AgentResponse messages;
• protocol adapters such as MCP, A2A, and ACP.

That means an agent can receive MCP-native text, images, embedded resources, or other content blocks where the provider and client support them. When a target only supports text, fast-agent projects the content to text at the adapter or provider boundary.

Example: transfer one agent's message history to another agent:

@fast.agent(name="haiku", model="haiku")
@fast.agent(name="openai", model="gpt-5.5")
async def main() -> None:
    async with fast.run() as agent:
        await agent.interactive(agent_name="haiku")
        await agent.openai.generate(agent.haiku.message_history)
        await agent.interactive(agent_name="openai")

For MCP resources and linked content, see Resources. For UI content returned by MCP servers, see mcp-ui and fast-agent.

Client mode

In client mode, fast-agent connects your agents to MCP servers. Configure MCP servers in fast-agent.yaml, AgentCards, or with CLI flags such as --url, --stdio, --npx, and --uvx.

Common client topics:

• Connect to MCP Servers
• Client OAuth
• Inspect MCP Servers
• MCP Resources
• mcp-ui and fast-agent

Server mode

In server mode, fast-agent exposes agents and workflows over MCP. Use the CLI for simple deployments, or use the Harness API with FastMCP when you want a custom server surface.

Common server topics:

• Run an MCP Server
• Custom MCP Servers
• Host on Hugging Face Spaces
• FastMCP Apps
• OpenAI Apps SDK

MCP features

fast-agent supports several MCP protocol features directly in the agent runtime:

• Skills over MCP
• Elicitations
• State Transfer
• Resources
• mcp-ui