Skip to main content

​
Overview

Fast Agent provides complete, end-to-end tested support for the Model Context Protocol (MCP), enabling agents to interact with external tools, resources, and data sources. It’s the first framework with full MCP feature support including Sampling and Elicitations.
Fast Agent includes advanced MCP transport diagnostics and OAuth support, making it the only tool that allows you to inspect Streamable HTTP Transport usage - critical for reliable, compliant deployments.

​
What is MCP?

The Model Context Protocol is a standardized protocol for connecting AI models to external tools and data sources. It defines:
  • Tools: Functions that agents can call to perform actions
  • Resources: Data that agents can access (files, APIs, databases)
  • Prompts: Reusable prompt templates with parameters
  • Sampling: Agents requesting LLM completions from servers
  • Roots: Filesystem roots for sandboxed operations

​
MCP Server Configuration

Configure MCP servers in your fastagent.config.yaml file: 
mcp:
  targets:
    - name: filesystem
      target: "npx -y @modelcontextprotocol/server-filesystem ."
    - name: fetch
      target: "uvx mcp-server-fetch"
    - name: time
      target: "uvx mcp-server-time"

​
Configuration Options

Launch servers via command:
mcp:
  servers:
    myserver:
      command: "uvx"
      args: ["mcp-server-package"]
      env:
        API_KEY: "${MYSERVER_API_KEY}"

​
Environment Variables

Use environment variable substitution: 
mcp:
  servers:
    github:
      command: "uvx"
      args: ["mcp-server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"

​
Attaching Servers to Agents

​
Static Configuration

Attach servers when defining the agent: 
@fast.agent(
    name="file_helper",
    instruction="Assist with file operations",
    servers=["filesystem"]  # MCP server from config
)

​
Multiple Servers

@fast.agent(
    name="web_researcher",
    instruction="Research topics online",
    servers=["fetch", "time", "browser"]
)

​
Runtime Attachment

Attach servers programmatically: 
from fast_agent.mcp.mcp_aggregator import MCPAttachOptions

# Attach at runtime
result = await agent.attach_mcp_server(
    server_name="new_server",
    server_config=server_settings,
    options=MCPAttachOptions(
        reconnect_on_failure=True,
        timeout_seconds=30
    )
)

if result.success:
    print(f"Attached: {result.tools_count} tools")
else:
    print(f"Failed: {result.error_message}")

​
Runtime Connection (AgentCards)

For AgentCard-based agents, use mcp_connect: 
---
name: research-agent
servers: []
mcp_connect:
  - target: "https://mcp.example.com/api"
    name: "research-api"
    auth:
      token: "${API_TOKEN}"
---

Research assistant with runtime MCP connection.

​
Using MCP Tools

Agents automatically discover and use tools from attached servers.

​
Automatic Tool Discovery

@fast.agent(
    name="developer",
    instruction="""You are a development assistant.
    Use available tools to help with coding tasks.""",
    servers=["filesystem", "git"]
)

async def main():
    async with fast.run() as agent:
        # Agent automatically uses filesystem tools
        await agent("Create a new Python file called main.py")
        
        # Agent automatically uses git tools
        await agent("Commit the changes")

​
Tool Filtering

Limit which tools are exposed: 
@fast.agent(
    name="reader",
    instruction="Read and analyze files",
    servers=["filesystem"],
    tools={
        "filesystem": ["read_file", "list_directory"]
        # Only these tools are available
    }
)

​
Pattern Matching

Use wildcards in tool filters: 
@fast.agent(
    name="math_agent",
    instruction="Perform calculations",
    servers=["calculator"],
    tools={
        "calculator": ["calc_*"]  # All tools starting with calc_
    }
)

​
Manual Tool Calls

from mcp.types import CallToolResult

result: CallToolResult = await agent.call_tool(
    name="filesystem__read_file",
    arguments={"path": "/path/to/file.txt"}
)

if not result.isError:
    content = result.content[0].text
    print(content)

​
Working with Resources

Resources provide read-only access to external data.

​
List Resources

# List all resources
resources = await agent.list_resources()

# List from specific server
resources = await agent.list_resources(namespace="filesystem")

​
Read Resources

from mcp.types import ReadResourceResult

result: ReadResourceResult = await agent.get_resource(
    resource_uri="file:///path/to/document.txt",
    namespace="filesystem"
)

for content in result.contents:
    if content.mimeType == "text/plain":
        print(content.text)

​
Send Messages with Resources

# Attach resource to message
response = await agent.with_resource(
    prompt_content="Summarize this document",
    resource_uri="file:///path/to/document.pdf",
    namespace="filesystem"
)

​
Resource Filtering

Limit resource access: 
@fast.agent(
    name="doc_reader",
    instruction="Read documentation",
    servers=["filesystem"],
    resources={
        "filesystem": ["file:///docs/*"]  # Only /docs/ path
    }
)

​
MCP Prompts

Prompts are reusable templates defined by MCP servers.

​
List Prompts

# List all available prompts
prompts = await agent.list_prompts()

# List from specific server
prompts = await agent.list_prompts(namespace="templates")

​
Apply Prompts

# Apply a prompt template
response = await agent.apply_prompt(
    "code_review",
    arguments={
        "language": "python",
        "file_path": "/src/main.py"
    }
)
print(response)

​
Store as Template

# Store prompt in agent context (persistent)
await agent.apply_prompt(
    "system_instructions",
    as_template=True  # Always included in context
)

​
Prompt Filtering

@fast.agent(
    name="reviewer",
    instruction="Code review assistant",
    servers=["templates"],
    prompts={
        "templates": ["review_*"]  # Only review prompts
    }
)

​
MCP Sampling

Sampling allows MCP servers to request LLM completions through your agent.

​
Configure Sampling

mcp:
  servers:
    ai_server:
      command: "uvx"
      args: ["my-mcp-server"]
      sampling:
        model: "haiku"  # Model to use for sampling

​
How It Works

  1. MCP server requests a completion
  2. Fast Agent routes to configured model
  3. Response is returned to server
  4. Server continues processing
Sampling enables MCP servers to use AI capabilities without direct LLM access, maintaining security and cost control.

​
MCP Roots

Roots define filesystem boundaries for MCP servers: 
mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      roots:
        - uri: "file:///workspace"
          name: "Project Workspace"
Roots provide security boundaries. Servers cannot access files outside their configured roots.

​
MCP Elicitations

Elicitations allow servers to request structured input from users: 
# Enable human input for elicitations
@fast.agent(
    name="interactive_agent",
    instruction="Request user input when needed",
    human_input=True  # Enables elicitation handling
)
When a server requests elicitation:
  1. User is prompted with a form
  2. Input is validated against schema
  3. Response is sent to server

​
OAuth Support

Fast Agent supports OAuth for HTTP/SSE MCP servers.

​
Basic OAuth Configuration

mcp:
  servers:
    secure_api:
      transport: http
      url: "https://api.example.com/mcp"
      auth:
        oauth: true
        redirect_port: 3030  # Local callback port
        redirect_path: /callback

​
OAuth Flow

  1. Server responds with authorization URL
  2. Browser opens for user authentication
  3. Callback captures authorization code
  4. Token is exchanged and stored securely
  5. Token is used for subsequent requests

​
Token Storage

Tokens are stored securely in your OS keychain via keyring:
  • macOS: Keychain
  • Windows: Credential Manager
  • Linux: Secret Service or KWallet

​
Memory-Only Storage

mcp:
  servers:
    temp_api:
      transport: http
      url: "https://api.example.com/mcp"
      auth:
        oauth: true
        persist: memory  # Don't persist tokens

​
MCP Transport Diagnostics

Fast Agent provides detailed transport diagnostics:

​
HTTP Transport Monitoring

# Get server status
status = await agent.get_server_status()

for server_name, info in status.items():
    print(f"{server_name}:")
    print(f"  Status: {info.status}")
    print(f"  Transport: {info.transport}")
    print(f"  Tools: {info.tools_count}")
    if info.error_message:
        print(f"  Error: {info.error_message}")

​
Connection Monitoring

# Enable transport diagnostics
fast-agent go --model sonnet

# Use /mcp command to inspect connections
> /mcp list
> /mcp session list
Fast Agent is the only framework with complete HTTP transport inspection capabilities, essential for production deployments.

​
MCP Ping Utility

Optional keep-alive mechanism: 
mcp:
  servers:
    long_running:
      command: "uvx"
      args: ["my-server"]
      ping_interval_seconds: 30  # Ping every 30 seconds
      max_missed_pings: 3        # Fail after 3 missed pings

​
Runtime MCP Management

​
Connect Servers Dynamically

# Connect from URL
result = await agent.attach_mcp_server(
    server_name="runtime_server",
    server_config=MCPServerSettings(
        transport="http",
        url="https://example.com/mcp"
    )
)

​
Disconnect Servers

# Detach server
result = await agent.detach_mcp_server("server_name")

if result.success:
    print("Server disconnected")

​
List Active Servers

# Get list of attached servers
servers = agent.list_attached_mcp_servers()
print(f"Active servers: {servers}")

​
MCP Sessions (Experimental)

Experimental support for server-side session management: 
# Create new session
await agent.experimental_sessions.create_session(
    server_name="api_server",
    title="Research Session"
)

# Resume existing session
await agent.experimental_sessions.resume_session(
    server_name="api_server",
    session_id="session-123"
)

# Clear sessions
await agent.experimental_sessions.clear_sessions("api_server")

​
Best Practices

Only attach servers that agents actually need. Each server adds initialization overhead and token usage for tool descriptions.
Use tool filters to limit the tool set exposed to agents. This improves performance and reduces token usage.
Always check CallToolResult.isError before using tool output. MCP tool calls can fail.
Use consistent URI schemes. Common patterns: file://, https://, resource://server/path
OAuth tokens are stored securely. Use memory-only storage for development/testing.
Configure appropriate models for sampling. Use cost-effective models unless quality is critical.

​
CLI Commands

​
Interactive MCP Management

# Start with MCP servers
fast-agent go --model sonnet

# MCP commands in interactive mode:
> /mcp list                    # List servers
> /mcp connect <target>        # Connect new server
> /mcp disconnect <server>     # Disconnect server
> /mcp reconnect <server>      # Reconnect server
> /mcp session list            # List sessions

​
Connect Remote MCP

# Connect to remote MCP server
fast-agent go --url https://hf.co/mcp

​
Next Steps

Agent Architecture

Learn how agents integrate with MCP

Configuration

Complete MCP configuration reference

MCP Servers

Available MCP servers and how to use them

Examples

See MCP integration examples

Build docs developers (and LLMs) love

Get started for freeTalk to us