name: hf-space-deployer
description: Deploy fast-agent MCP Servers to Hugging Face Spaces using Docker. Use when the user wants to deploy an "agent card" as an MCP Server. Includes templates and CLI commands for deploying agent cards with custom tools to HF Spaces.

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 FAST_AGENT_SERVE_OAUTH=hf is set, clients can authenticate two ways:

1. Direct Bearer token: Send Authorization: Bearer <HF_TOKEN> header
2. Simpler for programmatic clients

3. Client manages their own token

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

5. Better for interactive clients (like Claude Desktop)
6. 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/readme_template.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/dockerfile_template.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

2. Prepare directory with files:

3. README.md (use template)
4. Dockerfile (use template, update CMD with your agent card filename)
5. Your agent card (e.g., hf-api-agent.md)

6. Any tool Python files

7. Upload:
   bash hf upload evalstate/my-agent-space ./space-files --repo-type space

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

9. 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:
- FAST_AGENT_SERVE_OAUTH=hf is set
- --instance-scope request in CMD
- Client is sending Authorization: Bearer <token> header

Reference Files

• README template - Complete Space README.md with YAML
• Dockerfile template - Production-ready Dockerfile
• HF CLI reference - Detailed hf command documentation