Hf Space Deployer Skill for Claude

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

| | Shared Secrets | Token Passthrough |

|---|---|---|

| Who pays? | You (Space owner) | Users (their HF account) |

| Setup | Add API keys as Space secrets | Enable Space OAuth + FAST_AGENT_SERVE_OAUTH=huggingface + request scope |

| Best for | Internal tools, demos | Public deployments, multi-tenant |

| Models | Any provider | HF Inference only |

| Client auth | None required | Bearer token in header |

How Token Passthrough Works

When FAST_AGENT_SERVE_OAUTH=huggingface is set, clients can authenticate two ways:

• Direct Bearer token: Send Authorization: Bearer <HF_TOKEN> header
• Simpler for programmatic clients
• Client manages their own token

• 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. FAST_AGENT_SERVE_OAUTH=hf is also accepted, but current docs use huggingface.

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 AgentCard name becomes the MCP tool name. Use an explicit, stable name; the filename is only the path you pass to --agent-cards/--card.

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 (card name = MCP 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)
• For token passthrough: hf_oauth: true plus hf_oauth_scopes

Token passthrough frontmatter example:

---
title: My fast-agent MCP server
sdk: docker
app_port: 7860
hf_oauth: true
hf_oauth_expiration_minutes: 480
hf_oauth_scopes:
  - inference-api
---

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", "--agent-cards", "YOUR_AGENT_NAME.md", "--transport", "http", "--host", "0.0.0.0", "--port", "7860"]

Agent Card

Your agent card defines the agent's capabilities. The name 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

| Option | Flag | Example |

|--------|------|---------|

| Agent card | --agent-cards / --card | --agent-cards hf-api-agent.md |

| Multiple cards | --agent-cards / --card (repeat) | --agent-cards agent1.md --agent-cards agent2.md |

| Override model | --model | --model kimi |

| Shell access | --shell | --shell |

| Instance scope | --instance-scope | --instance-scope request |

| Transport | --transport | --transport http |

Instance Scope

Controls how agent instances are managed per MCP client:

| Scope | Behavior | Use Case |

|-------|----------|----------|

| shared (default) | Single instance for all requests | Trusted/private deployments, demos |

| connection | New instance per MCP connection/session | Multi-user with MCP session continuity |

| request | New instance per tool call; MCP sessions disabled | Public/token passthrough, per-request isolation |

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)

| Variable | Value | Description |

|----------|-------|-------------|

| FAST_AGENT_SERVE_OAUTH | huggingface | Enable HF authentication (hf is accepted alias) |

| FAST_AGENT_OAUTH_SCOPES | ${OAUTH_SCOPES} or inference-api | Required scopes; Spaces sets OAUTH_SCOPES when hf_oauth is enabled |

| FAST_AGENT_OAUTH_RESOURCE_URL | https://your-space.hf.space | Your Space's public URL; auto-derived from SPACE_HOST on Spaces if omitted |

from huggingface_hub import add_space_variable

SPACE_ID = "username/my-space"

add_space_variable(SPACE_ID, "FAST_AGENT_SERVE_OAUTH", "huggingface")
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")

Do not set a shared HF_TOKEN for user-scoped inference unless you intentionally want a server credential fallback. Enable Hugging Face OAuth in the Space README frontmatter with hf_oauth: true and hf_oauth_scopes.

Deployment Workflow

• Create Space:

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

• 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

• Upload:

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

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

• Access deployed agent at Space URL once built

Advanced Topics

Multiple Agent Cards

Serve multiple agents from one Space:

CMD ["fast-agent", "serve", \
     "--agent-cards", "agent1.md", \
     "--agent-cards", "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=huggingface is set
• README frontmatter has hf_oauth: true and the needed hf_oauth_scopes
• --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