MCP Servers

Connect Fleet agents to external tools and data sources using Model Context Protocol (MCP).

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI applications to securely connect to external data sources and tools. With MCP, Fleet agents can access tools from external servers—databases, APIs, file systems, and more—without those integrations being built into Fleet itself.

MCP servers expose:

Tools — Functions the agent can call
Resources — Data the agent can read
Prompts — Reusable prompt templates

How It Works

Configure servers — Define MCP servers in your Fleet configuration
Connect — Fleet connects to servers at startup (if auto_connect is enabled)
Discover tools — Agent sees MCP tools alongside built-in Fleet tools
Use tools — Agent calls MCP tools like any other tool

MCP tools appear in the agent's tool list with the naming pattern mcp_<server>_<tool>.

Transport Types

MCP supports three transport mechanisms:

Transport	Description	Use Case
`stdio`	Spawns a local process, communicates via stdin/stdout	Local tools, scripts
`sse`	Server-Sent Events over HTTP	Remote servers, cloud services
`websocket`	WebSocket connection	Real-time bidirectional communication

Global Configuration

Configure MCP servers in your Fleet config file:

Location: ~/Library/Application Support/com.usefamiliar.desktop/config.yaml

mcp:
  enabled: true
  default_timeout: 30s
  max_retries: 3
  retry_backoff: 2s
  servers:
    - name: github
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "{{vault:GITHUB_TOKEN}}"
      auto_connect: true

    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      auto_connect: true

    - name: remote-api
      transport: sse
      url: https://mcp.example.com/sse
      auto_connect: false

Global Settings

Field	Type	Default	Description
`enabled`	boolean	true	Enable/disable MCP system-wide
`default_timeout`	duration	30s	Default request timeout
`max_retries`	integer	3	Connection retry attempts
`retry_backoff`	duration	2s	Delay between retries

Server Configuration

Field	Type	Required	Description
`name`	string	Yes	Unique server identifier
`transport`	string	Yes	`stdio`, `sse`, or `websocket`
`command`	string	If stdio	Command to spawn the server
`args`	string[]	No	Command arguments
`url`	string	If sse/websocket	Server URL
`env`	map	No	Environment variables. Supports `{{vault:SECRET}}`
`auto_connect`	boolean	No	Connect on Fleet startup
`timeout`	duration	No	Override default timeout
`retry_attempts`	integer	No	Override max retries
`retry_delay`	duration	No	Override retry backoff

Per-Agent Configuration

Control which MCP servers an agent can access in its AGENT.md:

---
name: github-helper
description: Helps with GitHub tasks
model:
  provider: anthropic
  model: claude-sonnet-4-20250514

mcp_servers:
  - github
  - filesystem

mcp_permissions:
  github:
    allowed_tools: ["*"]
    denied_tools: ["delete_repo", "delete_branch"]
  filesystem:
    allowed_tools: ["read_file", "list_directory"]

mcp_approval_required:
  - github_create_issue
  - github_merge_pr
---

Fields

Field	Type	Description
`mcp_servers`	string[]	Names of MCP servers this agent can access
`mcp_permissions`	map	Fine-grained tool permissions per server
`mcp_approval_required`	string[]	MCP tools that require user approval before execution

Permission Rules

Each server can have its own permission configuration:

mcp_permissions:
  server_name:
    allowed_tools: ["*"]        # Allow all tools
    denied_tools: ["dangerous"] # Except these

Field	Type	Description
`allowed_tools`	string[]	Tools that are allowed. Use `"*"` for all tools.
`denied_tools`	string[]	Tools that are explicitly denied (takes precedence over allowed)

Evaluation order:

Check if tool is in denied_tools → Deny
Check if allowed_tools contains "*" → Allow
Check if tool is in allowed_tools → Allow
Otherwise → Deny

Tool Naming

MCP tools are prefixed with their server name:

mcp_<server>_<tool>

Examples:

Server github with tool create_issue → mcp_github_create_issue
Server filesystem with tool read_file → mcp_filesystem_read_file

This prevents naming collisions between servers and with built-in Fleet tools.

Example Configurations

GitHub Integration

Access GitHub repositories, issues, and pull requests:

servers:
  - name: github
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "{{vault:GITHUB_TOKEN}}"
    auto_connect: true

Available tools: list_repos, get_repo, create_issue, get_pull_request, create_review_comment, etc.

Local Filesystem

Read and write files on the local filesystem:

servers:
  - name: filesystem
    transport: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/Users/me/projects"
      - "/Users/me/documents"
    auto_connect: true

Available tools: read_file, write_file, list_directory, search_files

Postgres Database

Query a PostgreSQL database:

servers:
  - name: postgres
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: "{{vault:DATABASE_URL}}"
    auto_connect: true

Available tools: query, list_tables, describe_table

Remote Server via SSE

Connect to a remote MCP server:

servers:
  - name: company-api
    transport: sse
    url: https://mcp.company.com/sse
    auto_connect: false
    timeout: 60s

Using Secrets

MCP server configurations support vault secrets for sensitive values:

servers:
  - name: my-server
    transport: stdio
    command: my-mcp-server
    env:
      API_KEY: "{{vault:MY_API_KEY}}"
      DATABASE_URL: "{{vault:DB_CONNECTION_STRING}}"

Secrets are retrieved from the secure vault at connection time. See Secure Vault for managing secrets.

Requiring Approval

For sensitive operations, require user approval before tool execution:

mcp_approval_required:
  - github_merge_pr
  - github_delete_branch
  - postgres_query  # Approve all DB queries

When the agent tries to use these tools, Fleet will pause and ask for user confirmation before proceeding.

Managing Connections

Connection Status

Check MCP server status in Settings → MCP or via the agent dashboard. Status shows:

Connected/disconnected state
Last ping time
Number of available tools
Any connection errors

Manual Connect/Disconnect

Servers with auto_connect: false require manual connection. Use the MCP dashboard in Settings to:

Connect to a server
Disconnect from a server
View server capabilities

Reconnection

Fleet automatically attempts to reconnect if a server connection is lost:

Wait for retry_delay
Attempt reconnection
Repeat up to max_retries times
Log warning if all attempts fail

Building MCP Servers

You can build custom MCP servers to expose your own tools and data. Popular frameworks:

Python: FastMCP
TypeScript: MCP SDK

Example Python server with FastMCP:

from fastmcp import FastMCP

mcp = FastMCP("my-tools")

@mcp.tool()
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

@mcp.tool()
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

if __name__ == "__main__":
    mcp.run()

Then configure in Fleet:

servers:
  - name: my-tools
    transport: stdio
    command: python
    args: ["my_mcp_server.py"]
    auto_connect: true