MCP Servers

Overview

MCP servers provide tools, resources, and prompts that agents can use to interact with external systems. Fast Agent supports multiple transport types (stdio, SSE, HTTP) and provides flexible configuration options for connecting to MCP servers.

Basic Server Configuration

MCP servers are configured in the mcp.targets or mcp.servers section of your configuration file:

mcp:
  targets:
    - name: fetch
      target: "uvx mcp-server-fetch"
    - name: filesystem
      target: "npx -y @modelcontextprotocol/server-filesystem ."

Target Shorthand

The targets array provides a concise way to define servers using a target string that’s automatically parsed:

mcp:
  targets:
    - name: fetch
      target: "uvx mcp-server-fetch"  # stdio transport
    - name: huggingface  
      target: "https://huggingface.co/mcp?login"  # HTTP transport with OAuth
    - name: local-server
      target: "http://localhost:8001/mcp"  # HTTP transport

Transport Types

Fast Agent supports three MCP transport mechanisms:

stdio Transport

The default transport for local process-based servers:

command

string

required

The command to execute the server (e.g., npx, uvx, node, python).

args

array

Arguments for the server command.

mcp:
  servers:
    filesystem:
      transport: stdio
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

cwd

string

Working directory for the executed server command.

env

object

Environment variables to pass to the server process.

mcp:
  servers:
    brave:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-brave-search"]
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"

SSE Transport

Server-Sent Events transport for remote servers:

mcp:
  servers:
    remote-sse:
      transport: sse
      url: "http://localhost:8001/sse"
      read_transport_sse_timeout_seconds: 300

url

string

required

The SSE endpoint URL.

read_transport_sse_timeout_seconds

integer

default:"300"

Timeout in seconds for SSE connection.

HTTP Transport

Streamable HTTP transport for remote servers:

mcp:
  servers:
    remote-http:
      transport: http
      url: "http://localhost:8001/mcp"
      http_timeout_seconds: 60
      http_read_timeout_seconds: 30

url

string

required

The HTTP endpoint URL.

http_timeout_seconds

integer

Overall HTTP timeout in seconds. Defaults to MCP SDK default.

http_read_timeout_seconds

integer

HTTP read timeout in seconds. Defaults to MCP SDK default.

headers

object

Custom HTTP headers for connections.

headers:
  "Authorization": "Bearer ${API_TOKEN}"
  "X-Custom-Header": "value"

Fast Agent automatically infers the transport type based on the configuration:

If url is present: HTTP transport
If command is present: stdio transport
You can explicitly set transport to override this behavior

Server Connection Options

name

string

The name of the server, used to reference it in agent configurations.

description

string

Human-readable description of the server’s purpose.

load_on_start

boolean

default:"true"

Whether to connect to this server automatically when the agent starts.

include_instructions

boolean

default:"true"

Whether to include this server’s instructions in the system prompt.

reconnect_on_disconnect

boolean

default:"true"

Whether to automatically reconnect when the server session is terminated.When enabled, if a remote StreamableHTTP server returns a 404 indicating the session has been terminated (e.g., due to server restart), the client will automatically attempt to re-initialize the connection and retry the operation.

read_timeout_seconds

integer

Timeout in seconds for server operations.

MCP Ping Configuration

Client-side health checking for MCP servers using the MCP ping utility:

ping_interval_seconds

integer

default:"30"

Interval for MCP ping requests. Set to 0 or negative to disable pinging.

max_missed_pings

integer

default:"3"

Number of consecutive missed ping responses before treating the connection as failed.

mcp:
  servers:
    myserver:
      url: "http://localhost:8001/mcp"
      ping_interval_seconds: 30
      max_missed_pings: 3

Root Directories

For servers that work with filesystems, you can configure root directories to grant access:

roots

array

List of root directory configurations.

roots[].uri

string

required

The URI identifying the root. Must start with file://

roots[].name

string

Optional name for the root.

roots[].server_uri_alias

string

Optional URI alias for presentation to the server (useful for Docker containers).

Docker Example with Roots

mcp:
  targets:
    - name: interpreter
      target: "docker run -i --rm --pull=always -v ./agent_folder:/mnt/data/ ghcr.io/evalstate/mcp-py-repl:latest"
      roots:
        - uri: "file://./agent_folder/"
          name: "agent_folder"
          server_uri_alias: "file:///mnt/data/"

This configuration:

Mounts local ./agent_folder to /mnt/data/ in the container
Tells the server about the file://./agent_folder/ root
Uses server_uri_alias to translate paths for the containerized environment

MCP Sampling Configuration

Configure which model the MCP server uses for sampling operations:

sampling.model

string

default:"gpt-5-mini?reasoning=low"

Model to use for MCP sampling requests.

mcp:
  servers:
    sampling_resource:
      command: "uv"
      args: ["run", "sampling_resource_server.py"]
      sampling:
        model: "haiku"

MCP Elicitation Configuration

Control how the client handles elicitation requests from MCP servers:

elicitation.mode

string

default:"none"

Elicitation mode for interactive forms and user input:

forms: Display forms to users (default UI)
auto-cancel: Automatically cancel elicitation requests
none: No elicitation capability advertised

mcp:
  servers:
    elicitation_server:
      target: "uv run elicitation_server.py"
      elicitation:
        mode: "forms"

Authentication

See the OAuth configuration page for detailed authentication setup including OAuth 2.1 support.

Using Servers in Agents

Reference configured servers in your agent definitions:

@fast.agent(
    "researcher",
    "Search and analyze information from the web",
    servers=["fetch", "brave"],  # Names from config
)

Advanced Examples

Multiple Server Types

mcp:
  targets:
    # Local stdio servers
    - name: fetch
      target: "uvx mcp-server-fetch"
    
    - name: filesystem
      target: "npx -y @modelcontextprotocol/server-filesystem ."
    
    # Remote HTTP server with OAuth
    - name: huggingface
      target: "https://huggingface.co/mcp?login"
    
    # Docker container with volume mounts
    - name: interpreter
      target: "docker run -i --rm -v ./data:/mnt/data/ ghcr.io/evalstate/mcp-py-repl:latest"
      roots:
        - uri: "file://./data/"
          name: "data"
          server_uri_alias: "file:///mnt/data/"
    
    # Local server with environment variables
    - name: brave
      target: "npx -y @modelcontextprotocol/server-brave-search"
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"

Custom Headers and Timeouts

mcp:
  servers:
    api_server:
      transport: http
      url: "https://api.example.com/mcp"
      http_timeout_seconds: 120
      http_read_timeout_seconds: 60
      headers:
        "Authorization": "Bearer ${API_TOKEN}"
        "X-Client-Version": "1.0.0"
      ping_interval_seconds: 45
      max_missed_pings: 2

Experimental Features

experimental_session_advertise

boolean

default:"false"

Advertise MCP session test capability in client initialize payload.

experimental_session_advertise_version

integer

default:"2"

Reserved compatibility knob for session test capability advertisement.

Windows Configuration Notes

On Windows, some MCP servers require special path handling:

mcp:
  targets:
    # Use 'node' with absolute paths
    - name: filesystem
      target: "node c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js ."
    
    # Docker requires absolute paths for volume mounts
    - name: interpreter
      target: "docker run -i --rm -v x:/data:/mnt/data/ ghcr.io/evalstate/mcp-py-repl:latest"

Use npm -g root to find your global node_modules path.

Get Started

Core Concepts

Agent Types

Workflows

Features

CLI Reference

Configuration

Examples

Overview

Basic Server Configuration

Target Shorthand

Transport Types

stdio Transport

SSE Transport

HTTP Transport

Server Connection Options

MCP Ping Configuration

Root Directories

Docker Example with Roots

MCP Sampling Configuration

MCP Elicitation Configuration

Authentication

Using Servers in Agents

Advanced Examples

Multiple Server Types

Custom Headers and Timeouts

Experimental Features

Windows Configuration Notes

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agent Types

Workflows

Features

CLI Reference

Configuration

Examples

​Overview

​Basic Server Configuration

​Target Shorthand

​Transport Types

​stdio Transport

​SSE Transport

​HTTP Transport

​Server Connection Options

​MCP Ping Configuration

​Root Directories

​Docker Example with Roots

​MCP Sampling Configuration

​MCP Elicitation Configuration

​Authentication

​Using Servers in Agents

​Advanced Examples

​Multiple Server Types

​Custom Headers and Timeouts

​Experimental Features

​Windows Configuration Notes

​See Also

Build docs developers (and LLMs) love

Overview

Basic Server Configuration

Target Shorthand

Transport Types

stdio Transport

SSE Transport

HTTP Transport

Server Connection Options

MCP Ping Configuration

Root Directories

Docker Example with Roots

MCP Sampling Configuration

MCP Elicitation Configuration

Authentication

Using Servers in Agents

Advanced Examples

Multiple Server Types

Custom Headers and Timeouts

Experimental Features

Windows Configuration Notes

See Also