fast-agent (MCP server) — Use Cases, Install & Live Demo

Why use it

Key features

@fast.agent() / @fast.chain() / @fast.parallel() decorators for agent shapes
First-class MCP, Skills, and ACP support
Multi-model (Anthropic, OpenAI, Bedrock, local)
Built-in eval runner + trace visualizer
Can itself run as an MCP server, exposing your agents as tools

Live Demo

What it looks like in practice

fast-agent-mcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "fast-agent-mcp": {
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "fast-agent-mcp",
      "command": "uvx",
      "args": [
        "fast-agent-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "fast-agent-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fast-agent-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add fast-agent-mcp -- uvx fast-agent-mcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use fast-agent

Build a deep-research agent in 30 lines of Python

👤 Devs who want a reproducible research agent ⏱ ~60 min intermediate

When to use: You've prototyped 'research X' in chat and want it as a callable agent.

Prerequisites

Python 3.11+ and uv — Install uv if missing; fast-agent uses it
fast-agent installed — uvx fast-agent-mcp init; cd into the project

Flow

Scaffold

Use fast-agent. Generate a research agent skeleton with tavily search + fetch + summarize tools.✓ Copied

→ agent.py with @fast.agent decorator
Wire MCPs

Attach the tavily-mcp and filesystem MCP servers in fastagent.config.yaml.✓ Copied

→ Config validated; servers connect
Run + iterate

Run with: research 'state of small embedding models 2026'. Inspect the trace.✓ Copied

→ Trace shows search → fetch → summarize chain; output is a sourced brief
Add an eval

Author a 5-prompt eval; run nightly. Fail if any source citation is missing.✓ Copied

→ Eval output green/red; nightly cron set up

Outcome: A reproducible research pipeline you can hand to teammates.

Pitfalls

Decorator magic obscures what the agent is doing — Always read the trace; understand each tool call before declaring the agent works

Combine with: tavily-mcp · filesystem

Expose your fast-agent as an MCP server

👤 Devs sharing agents across teams ⏱ ~25 min intermediate

When to use: You built an internal agent in fast-agent and want others to call it from Claude.

Flow

Mark the agent as exposed

Add @fast.agent(expose=True) to the decorator; specify name and description for tool discovery.✓ Copied

→ Agent now also surfaces as an MCP tool
Run as MCP server

Run: fast-agent serve --transport stdio.✓ Copied

→ Stdio MCP server running with your agent listed as a tool
Add to clients

Add the fast-agent stdio config to my Claude Desktop config.✓ Copied

→ Tool visible in Claude; calling it invokes your agent

Outcome: Your custom agent reusable across the team like any other MCP.

Pitfalls

Agent depends on local files only the author has — Move config + assets into the agent's package; document any required env vars

Compare two prompt versions with the eval runner

👤 Anyone tuning a prompt for production ⏱ ~45 min intermediate

When to use: You're debating two prompt phrasings and want to pick by data.

Flow

Write the eval

Define an eval with 12 representative inputs and golden outputs.✓ Copied

→ evals/<name>.yaml
Run twice

Run eval against prompt v1, then v2. Compare pass rates + token usage.✓ Copied

→ Comparison table with deltas
Pick + lock

Save the winning prompt to prompts/winning.md; tag the eval as the regression baseline.✓ Copied

→ Locked baseline; future PRs run against it

Outcome: Data-driven prompt choice + regression net.

Pitfalls

12 inputs are all happy-path — Add adversarial cases — empty input, malformed input, contradictory facts

Combinations

Pair with other MCPs for X10 leverage

fast-agent-mcp + tavily-mcp + filesystem

Author a research agent with web + filesystem MCPs attached

Build a research agent that uses tavily for search, filesystem for note persistence.✓ Copied

fast-agent-mcp + mcpjam-inspector

Inspect your fast-agent server with the MCPJam UI before shipping

Run fast-agent as MCP server; connect via mcpjam-inspector to verify tool schemas.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
agent.run	messages, agent_name?	Drive an agent end-to-end	Model + tool calls
agent.list	—	Discover what's exposed	0
eval.run	eval_name, prompt_version?	Pre-commit / nightly regression	Model API per prompt
trace.get	run_id	Debug a specific run	0

Cost & Limits

What this costs to run

API quota: Whatever your chosen model provider's quota is
Tokens per call: Highly variable — depends on agent design
Monetary: Free framework; pay model providers
Tip: Use --model haiku-4.5 in dev; flip to sonnet for prod runs and evals

Security

Permissions, secrets, blast radius

Minimum scopes: Whatever attached MCPs need

Credential storage: fastagent.secrets.yaml (gitignored) or env vars

Data egress: To attached MCP servers and chosen model providers

Never grant: Production-write tokens to dev environments

Decorators can capture local context — watch for accidentally serializing secrets in agent state

Troubleshooting

Common errors and fixes

Agent loops without converging

Set max_steps; inspect the trace to find the loop. Often a tool returns ambiguous output and the model retries forever

Verify: trace.get(run_id)

Eval reports 0% but manual run works

Check golden_output format — strict equality vs semantic match

MCP server in config fails to attach

Run the server's command standalone first; verify env vars are present in fastagent.secrets.yaml

Slow first run

uv pulls deps on first call; cached on subsequent. Pre-warm in CI

Alternatives

fast-agent vs others

Alternative	When to use it instead	Tradeoff
PrefectHQ/fastmcp	You want the canonical MCP server framework, not a full agent framework	fastmcp is for building servers; fast-agent is for building (and orchestrating) agents that consume them
LangGraph	Your team is already invested in the LangChain ecosystem	More general; less MCP-native
mcp-agent (lastmile-ai)	You prefer a more minimal, tutorial-grade framework	Smaller scope; less batteries-included

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills