HF Space Deployer for Fast-Agent

Deploy fast-agent agents as MCP servers to Hugging Face Spaces using the hf CLI tool.

Choose Your Deployment Model

How Token Passthrough Works

When FASTAGENTSERVE_OAUTH=hf is set, clients can authenticate two ways:

1. Direct Bearer token: Send Authorization: Bearer <HF_TOKEN> header

- Simpler for programmatic clients - Client manages their own token

1. MCP OAuth flow: Full OAuth 2.1 discovery and authorization

- Better for interactive clients (like Claude Desktop) - Server exposes /.well-known/oauth-protected-resource for discovery

Both methods work - the server accepts either Authorization or X-HF-Authorization headers.

Quick Start

# 1. Create a Space
hf repo create <username>/<space-name> --repo-type space --space-sdk docker --exist-ok

# 2. Prepare files (see structure below)

# 3. Upload to Space
hf upload <username>/<space-name> <local-directory> --repo-type space --commit-message "Deploy fast-agent"

Space File Structure

Important: The agent card filename becomes the MCP tool name. Preserve your intentional naming!

space-directory/
├── README.md              # HF Space config with YAML header
├── Dockerfile             # Docker setup with Python 3.13 + uv
├── hf-api-agent.md        # Your agent card (filename = tool name)
└── hf_api_tool.py         # Optional: Python tools referenced in agent card

File Templates

README.md (Space Configuration)

See [references/readmetemplate.md](references/readmetemplate.md) for the complete template with YAML frontmatter.

Key fields:

• title: Space display name
• sdk: docker (required)
• app_port: 7860 (HF Spaces default)

Dockerfile

See [references/dockerfiletemplate.md](references/dockerfiletemplate.md) for the complete template.

FROM python:3.13-slim

RUN apt-get update && \
    apt-get install -y bash git git-lfs wget curl procps && \
    rm -rf /var/lib/apt/lists/*

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
RUN uv pip install --system --no-cache fast-agent-mcp

COPY --link ./ /app
RUN chown -R 1000:1000 /app
USER 1000

EXPOSE 7860

# Replace YOUR_AGENT_NAME.md with your actual agent card filename
CMD ["fast-agent", "serve", "--card", "YOUR_AGENT_NAME.md", "--transport", "http", "--host", "0.0.0.0", "--port", "7860"]

Agent Card

Your agent card defines the agent's capabilities. The filename becomes the MCP tool name:

---
type: agent
name: my-agent
function_tools:
  - tool_file.py:my_function
model: kimi
default: true
description: Agent description
---

# Agent Instructions

Your agent's instructions and capabilities...

Configuration Reference

CMD Options

Instance Scope

Controls how agent instances are managed per MCP client:

Required for token passthrough: Use --instance-scope request so each request uses the caller's token, not a shared one.

Environment Variables

For Shared Secrets (you pay)

Set API keys as Space secrets. All users share your keys:

from huggingface_hub import add_space_secret

add_space_secret("username/my-space", "HF_TOKEN", "hf_xxx")
add_space_secret("username/my-space", "OPENAI_API_KEY", "sk-xxx")

Or via Space Settings > Repository Secrets in the web UI.

For Token Passthrough (users pay)

from huggingface_hub import add_space_variable, add_space_secret

SPACE_ID = "username/my-space"

add_space_variable(SPACE_ID, "FAST_AGENT_SERVE_OAUTH", "hf")
add_space_variable(SPACE_ID, "FAST_AGENT_OAUTH_SCOPES", "inference-api")
add_space_variable(SPACE_ID, "FAST_AGENT_OAUTH_RESOURCE_URL", "https://username-my-space.hf.space")

# Dummy token required for startup
add_space_secret(SPACE_ID, "HF_TOKEN", "hf_dummy")

Deployment Workflow

1. Create Space:

``bash hf repo create evalstate/my-agent-space --repo-type space --space-sdk docker ``

1. Prepare directory with files:

- README.md (use template) - Dockerfile (use template, update CMD with your agent card filename) - Your agent card (e.g., hf-api-agent.md) - Any tool Python files

1. Upload:

``bash hf upload evalstate/my-agent-space ./space-files --repo-type space ``

1. Monitor build at https://huggingface.co/spaces/<username>/<space-name>

1. Access deployed agent at Space URL once built

Advanced Topics

Multiple Agent Cards

Serve multiple agents from one Space:

CMD ["fast-agent", "serve", \
     "--card", "agent1.md", \
     "--card", "agent2.md", \
     "--transport", "http", \
     "--host", "0.0.0.0", \
     "--port", "7860", \
     "--instance-scope", "request"]

Additional Dependencies

Add packages to the Dockerfile:

RUN uv pip install --system --no-cache \
    fast-agent-mcp \
    requests \
    pandas

Or use a requirements.txt:

COPY requirements.txt .
RUN uv pip install --system --no-cache -r requirements.txt

Troubleshooting

Build fails: Check Space build logs for missing dependencies or syntax errors

Space runs but errors: Verify:

• Port is 7860
• Tool files exist and have correct paths
• API keys are configured in secrets

Tool import errors: Ensure tool files are in the Space root directory with your agent card

Token passthrough not working: Check:

• FASTAGENTSERVE_OAUTH=hf is set
• --instance-scope request in CMD
• Client is sending Authorization: Bearer <token> header

Reference Files

• [README template](references/readme_template.md) - Complete Space README.md with YAML
• [Dockerfile template](references/dockerfile_template.md) - Production-ready Dockerfile
• [HF CLI reference](references/hfclicommands.md) - Detailed hf command documentation