PRIVATE_SPACE_GUIDE.md

Private Space Testing Guide

The 404 Problem: Is Your Space Private?

If you're getting 404 errors, your Space might be PRIVATE, which requires authentication to access.

Check Your Space Visibility

The settings page should now be open in your browser. Look for:

🔒 Private Space

Visibility: Private
Only you and approved users can access this Space

🌐 Public Space

Visibility: Public
Anyone can access this Space

Solution 1: Make Your Space Public (Recommended for APIs)

Steps:

1. Go to: https://huggingface.co/spaces/ocx2025/basicsearch/settings
2. Scroll to "Visibility" section
3. Click "Make public"
4. Confirm the change

After Making Public:

# Wait 30 seconds, then test again
sleep 30
cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch
uv run python test_deployment.py

✅ Pros:

• No authentication needed
• Easy to test
• Anyone can use your API
• Better for integrations

❌ Cons:

• Anyone can see your code
• Anyone can use your API
• Public usage counts

Solution 2: Keep Private + Use Authentication Token

If you want to keep the Space private, you'll need a Hugging Face token.

Get Your Token:

1. Visit: https://huggingface.co/settings/tokens
2. Click "New token"
3. Name it: basicsearch-testing
4. Select permissions: Read
5. Click "Generate"
6. Copy the token (starts with hf_...)

Test with Token:

cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch

# Replace YOUR_TOKEN with actual token
python test_private_space.py https://ocx2025-basicsearch.hf.space hf_YourTokenHere

Set as Environment Variable:

# Add to ~/.zshrc or ~/.bashrc
export HF_TOKEN="hf_YourTokenHere"

# Then you can just run:
python test_private_space.py

Update Test Script to Use Token:

# test_deployment.py with auth
import os
import requests

token = os.getenv("HF_TOKEN")
headers = {}
if token:
    headers["Authorization"] = f"Bearer {token}"

response = requests.get(
    "https://ocx2025-basicsearch.hf.space/health",
    headers=headers
)

✅ Pros:

• Code stays private
• Control who can access
• Better security

❌ Cons:

• Requires token management
• More complex testing
• Harder to share

Test Right Now

Quick Check:

# Test without auth (works if public)
curl https://ocx2025-basicsearch.hf.space/health

# Test with auth (works if private)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://ocx2025-basicsearch.hf.space/health

Expected Results:

If Space is Building:

404 - Page not found (with HF branding page)

Action: Wait 5-10 more minutes

If Space is Private:

404 - Page not found

Action: Make public OR use token

If Space is Public and Running:

{"status": "ok"}

Action: Celebrate! 🎉

How to Use Private Space with Claude

If you keep it private, you'll need to configure Claude with your token:

Claude Desktop Config:

{
  "mcpServers": {
    "basicsearch": {
      "url": "https://ocx2025-basicsearch.hf.space",
      "headers": {
        "Authorization": "Bearer hf_YourTokenHere"
      }
    }
  }
}

Docker App with Authentication

If you want your Docker app to handle authentication, update app.py:

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

# Simple token check
API_TOKEN = os.getenv("API_TOKEN", "")

@app.get("/health")
async def health(authorization: str = Header(None)):
    if API_TOKEN and authorization != f"Bearer {API_TOKEN}":
        raise HTTPException(status_code=401, detail="Unauthorized")
    return {"status": "ok"}

Comparison: Public vs Private

Feature	Public	Private
Access	Anyone	Token required
Testing	Easy	Needs token
Security	Low	High
Sharing	Easy	Controlled
API Use	Simple	Complex
Best For	Demos, Open APIs	Internal tools

Recommendation for Your MCP Server

Choose Public If:

• ✅ You want easy testing
• ✅ You plan to share with others
• ✅ Your API is meant to be public
• ✅ No sensitive data involved
• ✅ You want Claude integration to be simple

Choose Private If:

• ✅ You have sensitive code
• ✅ You want to control access
• ✅ You're in development phase
• ✅ You need usage tracking
• ✅ You have private API keys (like YouTube API)

Current Status Check

Run this to determine what's happening:

cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch

# Check 1: Is it accessible at all?
curl -I https://ocx2025-basicsearch.hf.space/health

# Check 2: What's the space status?
open https://huggingface.co/spaces/ocx2025/basicsearch

# Check 3: What are the settings?
open https://huggingface.co/spaces/ocx2025/basicsearch/settings

Look for:

1. "Building" → Wait and try again
2. "Running" + Private → Make public or use token
3. "Running" + Public → Should work!
4. "Error" → Check logs

Quick Fix Checklist

• Visit: https://huggingface.co/spaces/ocx2025/basicsearch/settings
• Check visibility: Public or Private?
• If Private: Click "Make public"
• If keeping Private: Get HF token from https://huggingface.co/settings/tokens
• Wait 30 seconds after change
• Run: uv run python test_deployment.py
• Should see: ✓ PASSED messages!

Troubleshooting Matrix

Status	Visibility	Result	Action
Building	Any	404	Wait
Running	Public	200 OK	✅ Success
Running	Public	404	Check logs
Running	Private	404	Use token or make public
Running	Private	401	Invalid token
Error	Any	404	Check build logs

After Making Public

Once you make it public, test immediately:

# Should work now!
curl https://ocx2025-basicsearch.hf.space/health

# Full test
uv run python test_deployment.py

# If it works, you'll see:
# ✓ PASSED - Health Check
# ✓ PASSED - Service Info
# ... etc

Security Note

If you make the Space public, your code will be visible. Make sure:

• ✅ No API keys in code (use Hugging Face secrets)
• ✅ No passwords or tokens committed
• ✅ Your .gitignore includes .env files
• ✅ Secrets are set in Space settings, not code

Your YOUTUBE_API_KEY is safe because it's in Space secrets, not code! ✅

Summary

Most likely issue: Your Space is private and needs authentication.

Quick fix:

1. Open settings (should be open now)
2. Click "Make public"
3. Wait 30 seconds
4. Run test again
5. Profit! 🚀