Higgsfield MCP v Claude Code a OpenCode

Vytvořeno: 2.5.2026 | Aktualizováno: 09.05.2026 07:17

Higgsfield MCP je oficiální MCP konektor pro generování obrázků a videí přes Higgsfield. Oficiální návod používá endpoint https://mcp.higgsfield.ai/mcp a autentizaci přes Higgsfield účet, ne API key/API secret.

Tento zápisek popisuje konkrétní nasazení v Claude Code a OpenCode běžících v Dockeru. Důležité je hlavně zachytit rozdíl: v Claude Code OAuth proběhl rychle, zatímco v OpenCode se objevily chyby kolem OAuth scope. Nakonec fungovaly dvě cesty: device flow s tokenem platným jen 24 hodin a praktičtější převzetí delšího tokenu z Claude Code. Vedle remote MCP dnes existují i dvě oficiální navazující cesty: Higgsfield CLI pro terminálové použití a Higgsfield AI Skills pro agenty. Neoficiální lokální MCP wrappery nad API key/API secret jsou v článku ponechané až jako okrajová alternativa.

Cíl byl připojit Higgsfield MCP do dvou klientů:

• Claude Code
• OpenCode

Higgsfield na své MCP stránce uvádí, že není potřeba spravovat API klíče. API key a API secret z Higgsfield API proto nejsou totéž jako autentizace pro oficiální MCP endpoint. Pro MCP se používá OAuth přihlášení přes Higgsfield účet.

Dnes je dobré rozlišovat tři oficiální vrstvy:

• remote MCP endpoint – integrace přes https://mcp.higgsfield.ai/mcp, vhodná pro MCP klienty
• Higgsfield CLI – oficiální terminálový nástroj higgsfield pro generování obrázků/videí, správu účtu, modelů, workspace, uploadů a Soul ID
• Higgsfield AI Skills – Markdown skills pro agenty, které obalují práci s Higgsfield CLI a dávají agentovi konkrétní workflow pro generování, Soul ID, produktové fotky a marketplace karty

Higgsfield CLI je oficiální příkazový nástroj pro práci s Higgsfieldem z terminálu. Podle README umí generovat obrázky a videa přes více než 30 modelů, včetně Nano Banana Pro, FLUX.2, Soul V2, Veo 3.1, Kling v3.0, Seedance 2.0 a Marketing Studio.

Důležité: CLI není náhrada MCP endpointu ve smyslu remote MCP serveru. Je to ale oficiální cesta, jak Higgsfield používat v prostředí, kde agent umí spouštět shell příkazy. Pokud není potřeba MCP tool interface a stačí terminálové volání, dává oficiální CLI větší smysl než komunitní lokální wrapper nad API key/API secret.

README uvádí několik instalačních cest.

macOS / Linux přes instalační skript:

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

macOS / Linux přes Homebrew:

brew install higgsfield-ai/tap/higgsfield

Cross-platform instalace přes npm:

npm install -g @higgsfield/cli

Po instalaci se provede přihlášení:

higgsfield auth login

Jednoduché vygenerování obrázku s čekáním na výsledek:

higgsfield generate create nano_banana_2 --prompt "a quiet beach at sunrise" --wait

Příklad pro Nano Banana Pro:

higgsfield generate create nano_banana_2 \
  --prompt "modern architecture, glass facade, golden hour light" \
  --aspect_ratio 16:9 \
  --resolution 2k \
  --wait

Příklad pro video přes Kling v3.0 se vstupním obrázkem:

higgsfield generate create kling3_0 \
  --prompt "slow camera push through a forest clearing at dawn" \
  --start-image ./first.png \
  --duration 5 --mode pro --sound off \
  --wait

Podle README CLI obsahuje tyto skupiny příkazů:

• higgsfield auth – login, logout a kontrola tokenu
• higgsfield account – stav kreditů a transakce
• higgsfield workspace – výběr billing workspace
• higgsfield model – seznam modelů a schémata parametrů
• higgsfield generate – vytvoření, nacenění, čekání, načtení a listování jobů
• higgsfield upload – upload image/video/audio souborů
• higgsfield soul-id – trénování a správa Soul postav
• higgsfield marketing-studio – branded ads s avatary, produkty a referencemi
• higgsfield product-photoshoot – produktové fotky s mode-specific enhancement
• higgsfield version – informace o buildu

Praktické flagy:

• –wait – počká na dokončení jobu a vypíše URL výsledku
• –wait-timeout – maximální čekání, výchozí hodnota je podle README 10m
• –wait-interval – interval pollingu, výchozí hodnota je 3s
• –json – strojově čitelný JSON výstup
• –no-color – vypnutí barevného výstupu

Příklad pipeline s JSON výstupem:

higgsfield generate list --json | jq -r '.[] | select(.status=="completed") | .result_url'

Pro Claude Code a OpenCode jsou tím pádem tři praktické varianty:

1. MCP endpoint – nejlepší, pokud MCP klient zvládne OAuth vůči https://mcp.higgsfield.ai/mcp.
2. Oficiální CLI – vhodné, pokud agent umí spouštět shell příkazy a stačí mu příkaz higgsfield místo MCP toolů.
3. Neoficiální lokální MCP wrappery – až fallback, pokud je potřeba MCP rozhraní, ale remote OAuth nefunguje a zároveň nestačí CLI.

Higgsfield AI Skills je oficiální sada Markdown-based skills pro AI coding agenty. README uvádí podporu pro Claude Code, Cursor, Codex a další agenty, které umí načítat Markdown skills. Instalace zároveň řeší instalaci Higgsfield CLI a autentizaci jako součást setupu.

Doporučená cross-agent instalace:

npx skills add higgsfield-ai/skills

Alternativa přes GitHub CLI 2.90+:

gh skill install higgsfield-ai/skills

Instalace přes Claude Code marketplace:

/plugin marketplace add higgsfield-ai/skills
/plugin install higgsfield@higgsfield

Fallback přes clone repozitáře:

git clone --depth 1 https://github.com/higgsfield-ai/skills.git
cd skills
./setup

Repozitář aktuálně popisuje čtyři hlavní skills:

Důležitý princip: skills neřeší jen jednorázový příkaz. Dávají agentovi workflow – například nejdřív natrénovat Soul ID a potom ho použít v generování nebo v Marketing Studio jobech.

Skills dávají smysl hlavně tehdy, když:

• agent umí načíst Markdown skills a spouštět shell příkazy
• je potřeba agentovi dát konkrétní pracovní postup místo ručního skládání parametrů
• stačí CLI workflow a není nutné mít každý Higgsfield endpoint jako samostatný MCP tool
• jde o opakované úlohy typu produktové fotky, marketplace karty, Soul ID nebo branded ad video

Pro čisté MCP workflow dál platí sekce níže. Pro agentní práci, kde je povolené volání terminálu, je ale oficiální kombinace Higgsfield CLI + Higgsfield AI Skills preferovaná před komunitními lokálními wrappery.

V Claude Code stačí nakonfigurovat vzdálený HTTP MCP server:

claude mcp add --transport http higgsfield https://mcp.higgsfield.ai/mcp

Ekvivalentní ruční konfigurace v ~/.claude.json:

"higgsfield": {
  "type": "http",
  "url": "https://mcp.higgsfield.ai/mcp"
}

Po restartu Claude Code se autentizace spustí přes /mcp. Claude Code otevře OAuth odkaz, uživatel se přihlásí do Higgsfield účtu a token se uloží do Claude credentials.

Claude Code v mém prostředí běží v Dockeru. Při OAuth flow Claude Code vytvořil callback adresu:

http://localhost:65498/callback

Proto bylo nutné zajistit, aby se prohlížeč na hostitelském systému dostal na port 65498 v kontejneru. Jinak se sice otevře autorizační odkaz, ale callback po přihlášení se nemá kam vrátit.

Typicky to znamená publikovat port při spuštění kontejneru:

docker run -p 127.0.0.1:65498:65498 ...

Nebo v docker-compose.yml:

ports:
  - "127.0.0.1:65498:65498"

Pokud se port doplní až dodatečně, je potřeba kontejner znovu vytvořit/restartovat podle použitého Docker workflow.

Do /home/ubuntu/.config/opencode/opencode.json jsem nejdřív přidal Higgsfield jako remote MCP server s OAuth:

"higgsfield": {
  "type": "remote",
  "url": "https://mcp.higgsfield.ai/mcp",
  "oauth": {},
  "enabled": true
}

OpenCode pak spustil OAuth flow, ale v prohlížeči se objevila chyba:

The requested scope is invalid, unknown, or malformed. The OAuth 2.0 Client is not allowed to request scope 'openid'.

Otevřená autorizační URL mířila na Clerk:

https://clerk.higgsfield.ai/oauth/authorize?...&scope=openid+profile+email&resource=https://mcp.higgsfield.ai/

Problém byl v tom, že OpenCode posílal scope openid, který Higgsfield/Clerk pro daného dynamicky registrovaného klienta nepovolil.

Claude Code použil předregistrovaného OAuth klienta pro Higgsfield. V uložených credentials bylo vidět, že Claude Code měl pro Higgsfield uložené:

• serverUrl: https://mcp.higgsfield.ai/mcp
• clientId: předregistrovaný klient Claude Code
• redirectUri: http://localhost:65498/callback
• scope včetně openid, profile, email a offline_access

OpenCode naproti tomu použil vlastní OAuth flow s jiným callbackem, například:

http://127.0.0.1:19876/mcp/oauth/callback

Když jsem se pokusil použít stejný clientId jako Claude Code, vznikla jiná chyba:

{"error":"invalid_request","error_description":"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. The 'redirect_uri' parameter does not match any of the OAuth 2.0 Client's pre-registered redirect urls."}

To dává smysl: předregistrovaný klient Claude Code má povolený callback pro Claude Code, ne callback OpenCode. Přepsání clientId tedy samo o sobě nestačí.

Zkoušel jsem:

• nechat OpenCode udělat OAuth automaticky přes oauth: {}
• přidat do OpenCode stejný clientId, který použil Claude Code
• zkusit nastavit scope bez openid

Ani poslední úprava nezabrala. V mém setupu zůstal problém v OAuth toku OpenCode: buď se požadoval nepovolený scope openid, nebo neseděl redirect_uri vůči použitému klientovi.

Později jsem našel pokyn pro OpenClaw, že Higgsfield MCP podporuje OAuth device flow. To je pro OpenCode zajímavé, protože device flow nepotřebuje lokální redirect_uri ani callback port do Docker kontejneru. Uživatel jen otevře autorizační odkaz, potvrdí přihlášení a agent mezitím polluje token endpoint.

OAuth protected resource discovery pro Higgsfield uvádí dva authorization servery:

• https://clerk.higgsfield.ai pro authorization-code PKCE flow
• https://fnf-device-auth.higgsfield.ai pro device-code flow

Pro device flow je důležitý server fnf-device-auth.higgsfield.ai. Jeho OpenAPI schema ukazuje dva hlavní endpointy:

• POST /authorize – vrátí device_code, verification_uri, expires_in a interval
• POST /token – po potvrzení uživatelem vrátí access_token, token_type a expires_in

Získání device kódu:

curl -s https://fnf-device-auth.higgsfield.ai/authorize \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{}'

Odpověď má tvar:

{
  "device_code": "...",
  "verification_uri": "https://higgsfield.ai/device?code=...",
  "expires_in": 600,
  "interval": 5
}

Uživatel otevře verification_uri v prohlížeči a přihlásí se do Higgsfield účtu. Po potvrzení se začne pollovat token endpoint:

curl -s https://fnf-device-auth.higgsfield.ai/token \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"device_code":"SEM_VLOZ_DEVICE_CODE"}'

Po úspěšném potvrzení se vrátí Bearer token:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Tento token je možné uložit do stejného souboru, který používá OpenCode:

install -m 600 /dev/null /home/ubuntu/.config/opencode/higgsfield.token
# do souboru zapsat pouze access_token, bez uvozovek a bez prefixu Bearer

OpenCode konfigurace zůstává stejná jako u Bearer workaroundu:

"higgsfield": {
  "type": "remote",
  "url": "https://mcp.higgsfield.ai/mcp",
  "headers": {
    "Authorization": "Bearer {file:./higgsfield.token}"
  },
  "oauth": false,
  "enabled": true
}

Device flow se podařilo dokončit a token fungoval, ale v odpovědi byl parametr:

"expires_in": 86400

To znamená platnost jen 24 hodin. Navíc device flow nevrací refresh token, takže tiché obnovení není možné – každý den by bylo nutné opakovat celý flow s prohlížečem. Proto jsem se po testu vrátil k tokenu převzatému z Claude Code credentials, který přináší i refresh token a umožňuje automatické obnovování.

Protože Claude Code už měl vůči Higgsfield úspěšně získaný OAuth token, nejrychlejší funkční řešení bylo:

1. vytáhnout Higgsfield access token a refresh token z Claude Code credentials
2. uložit je do souborů pro OpenCode
3. v OpenCode vypnout OAuth flow a posílat access token jako statický Bearer header

Access token má vždy platnost 24 hodin – pevně dané na straně Higgsfield serveru, nedá se změnit. Claude Code při OAuth flow ukládá vedle access tokenu i refresh token: ten je dlouhodobý a slouží k tichému získání nového access tokenu bez opakovaného přihlašování v prohlížeči. Oba tokeny je při první extrakci potřeba uložit. Jak využít refresh token k automatickému obnovování, popisuje sekce Automatická obnova tokenu níže.

Token se nachází v souboru:

~/.claude/.credentials.json

V sekci mcpOAuth je položka pro Higgsfield. Tokeny se dají bezpečně zkopírovat do samostatných souborů bez vypisování jejich hodnot do terminálu:

import json
from pathlib import Path
 
credentials_path = Path.home() / ".claude" / ".credentials.json"
target_path = Path.home() / ".config" / "opencode" / "higgsfield.token"
refresh_path = Path.home() / ".config" / "opencode" / "higgsfield_refresh.token"
 
with credentials_path.open() as f:
    data = json.load(f)
 
for item in data.get("mcpOAuth", {}).values():
    if item.get("serverName") == "higgsfield" or item.get("serverUrl") == "https://mcp.higgsfield.ai/mcp":
        access_token = item["accessToken"]
        refresh_token = item.get("refreshToken", "")
        break
else:
    raise SystemExit("Higgsfield token nebyl v Claude Code credentials nalezen")
 
target_path.write_text(access_token.strip())
target_path.chmod(0o600)
print(f"Access token uložen do {target_path}")
 
if refresh_token:
    refresh_path.write_text(refresh_token.strip())
    refresh_path.chmod(0o600)
    print(f"Refresh token uložen do {refresh_path}")
else:
    print("Refresh token nebyl nalezen – automatický refresh nebude fungovat")

OpenCode konfigurace pak vypadá takto:

"higgsfield": {
  "type": "remote",
  "url": "https://mcp.higgsfield.ai/mcp",
  "headers": {
    "Authorization": "Bearer {file:./higgsfield.token}"
  },
  "oauth": false,
  "enabled": true
}

Soubory higgsfield.token a higgsfield_refresh.token jsou relativní k adresáři s opencode.json, tedy typicky v ~/.config/opencode/.

Tím se OAuth flow v OpenCode úplně obejde a OpenCode použije již existující token získaný přes Claude Code.

Higgsfield vydává access tokeny vždy s platností 24 hodin. Při prvním OAuth flow Claude Code ale uloží do credentials dva tokeny:

• access_token – krátkodobý Bearer token pro API volání, vyprší za 24 hodin
• refresh_token – dlouhodobý token pro tiché obnovení; nepotřebuje prohlížeč ani přihlašování

Refresh flow funguje tak, že skript zavolá Higgsfield OAuth token endpoint s refresh tokenem. Server vydá nový access token a obvykle i rotovaný refresh token (starý se nahradí novým).

Uložit jako ~/.config/opencode/refresh-higgsfield-token.sh a nastavit jako spustitelný:

#!/bin/bash
# Refreshes Higgsfield OAuth access token using stored refresh token.
# Higgsfield issues tokens with 24h validity; run this every ~20h via cron.
 
set -euo pipefail
 
REFRESH_TOKEN_FILE="$HOME/.config/opencode/higgsfield_refresh.token"
ACCESS_TOKEN_FILE="$HOME/.config/opencode/higgsfield.token"
CLIENT_ID="zWX6QppKmYmSXa1S"
TOKEN_ENDPOINT="https://mcp.higgsfield.ai/oauth2/token"
 
REFRESH_TOKEN=$(cat "$REFRESH_TOKEN_FILE")
 
RESPONSE=$(curl -s -X POST "$TOKEN_ENDPOINT" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=${REFRESH_TOKEN}&client_id=${CLIENT_ID}")
 
ACCESS_TOKEN=$(echo "$RESPONSE" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['access_token'])")
NEW_REFRESH_TOKEN=$(echo "$RESPONSE" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('refresh_token',''))")
 
if [ -z "$ACCESS_TOKEN" ]; then
  echo "ERROR: Failed to refresh token. Response: $RESPONSE" >&2
  exit 1
fi
 
echo -n "$ACCESS_TOKEN" > "$ACCESS_TOKEN_FILE"
 
if [ -n "$NEW_REFRESH_TOKEN" ]; then
  echo -n "$NEW_REFRESH_TOKEN" > "$REFRESH_TOKEN_FILE"
fi
 
echo "$(date): Higgsfield token refreshed OK"

chmod +x ~/.config/opencode/refresh-higgsfield-token.sh

Ruční spuštění (test nebo při vypršení tokenu):

~/.config/opencode/refresh-higgsfield-token.sh

Na Alpine s busyboxem standardní příkaz crontab bez SUID bitu nefunguje jako běžný uživatel – crontab soubor je potřeba zapsat přímo jako root. Nahraď <user> svým uživatelským jménem a uprav cestu ke skriptu:

sudo bash -c 'echo "0 */20 * * * /home/<user>/.config/opencode/refresh-higgsfield-token.sh >> /tmp/higgsfield-token-refresh.log 2>&1" > /var/spool/cron/crontabs/<user>'
sudo chown <user> /var/spool/cron/crontabs/<user>
sudo chmod 600 /var/spool/cron/crontabs/<user>

Interval */20 znamená spuštění každých 20 hodin – s dostatečnou rezervou před vypršením 24hodinového limitu.

Spuštění crond, pokud ještě neběží:

sudo crond -b -l 8

Pokud má crond startovat automaticky při restartu kontejneru nebo systému, přidá se startup skript do /etc/local.d/:

sudo bash -c 'cat > /etc/local.d/crond.start << "EOF"
#!/bin/sh
crond -b -l 8
EOF
chmod +x /etc/local.d/crond.start'

Při dalším startu systému se crond spustí automaticky.

Vedle oficiálního remote endpointu, oficiálního CLI a oficiálních skills existují také neoficiální lokální MCP servery, které neřeší OAuth proti https://mcp.higgsfield.ai/mcp, ale obalují Higgsfield API a používají API key/API secret. Po nalezení oficiálního CLI a skills bych tuto cestu bral jen jako fallback: hodí se hlavně tehdy, když je nezbytné lokální MCP rozhraní a zároveň nefunguje remote OAuth ani nestačí spouštět oficiální CLI.

V diskusi jsem porovnával hlavně dva repozitáře od stejného autora:

• geopopos/higgsfield_ai_mcp
• geopopos/geo_higgsfield_ai_mcp

Oba projekty používají lokální Python server a credentials z Higgsfield API. Prakticky to znamená, že OpenCode by nepřipojoval type: remote endpoint Higgsfieldu, ale lokálně spuštěný příkaz přes type: local.

higgsfield_ai_mcp dává smysl, pokud jde hlavně o rychlé lokální napojení Higgsfieldu přes API key/API secret a základní generování obrázků nebo videa. Je jednodušší a podle README míří hlavně na rychlé použití s Claude Desktopem a FastMCP.

geo_higgsfield_ai_mcp dává větší smysl, pokud je potřeba více kontroly nad parametry Higgsfield API: batch generation, seed, rozměry, webhooky, speech video, motion strength nebo správa character references. README u něj obsahuje i quick setup pro Claude Code.

Oba repozitáře používají stejný Python import namespace i stejný command/distribution název:

higgsfield_mcp
higgsfield-mcp

Proto je nedává smysl instalovat vedle sebe do stejného Python prostředí. Pokud by se testovaly oba, je lepší použít oddělené virtualenv/uv prostředí nebo kontejnery, jinak si mohou navzájem přepsat package a příkaz.

Pro lokální MCP server by konfigurace v OpenCode nebyla remote OAuth konfigurace, ale lokální příkaz. Konkrétní příkaz záleží na tom, jak je balíček nainstalovaný, ale princip je tento:

"higgsfield-local": {
  "type": "local",
  "command": ["higgsfield-mcp"],
  "environment": {
    "HIGGSFIELD_API_KEY": "{file:./higgsfield-api.key}",
    "HIGGSFIELD_SECRET": "{file:./higgsfield-api.secret}"
  },
  "enabled": true
}

U projektu higgsfield_ai_mcp je podle README potřeba použít proměnné HF_API_KEY a HF_SECRET místo HIGGSFIELD_API_KEY a HIGGSFIELD_SECRET:

"environment": {
  "HF_API_KEY": "{file:./higgsfield-api.key}",
  "HF_SECRET": "{file:./higgsfield-api.secret}"
}

Výhody:

• obejdou problematické OAuth flow v OpenCode
• používají běžné API key/API secret, které se dají uložit přes {file:…}
• běží lokálně a dají se případně upravit

Nevýhody:

• nejsou to oficiální Higgsfield MCP endpointy
• po existenci oficiálního CLI a skills jsou méně preferovaná cesta
• mohou pokrývat jen část funkcí oficiálního MCP konektoru nebo CLI
• je potřeba řešit instalaci Python prostředí a závislostí
• oba porovnávané projekty kolidují názvem balíčku/příkazu
• bezpečnost API key/API secret je na lokální konfiguraci

Po úpravě konfigurace je potřeba restartovat OpenCode nebo otevřít novou session, aby se konfigurace znovu načetla.

Základní kontrola:

opencode mcp list

Pokud se později začne vracet 401 Unauthorized, nejpravděpodobnější příčina je expirovaný token. Možnosti jsou:

• spustit refresh skript ~/.config/opencode/refresh-higgsfield-token.sh – obnoví token bez prohlížeče a bez přihlašování
• znovu provést přihlášení v Claude Code přes /mcp a znovu extrahovat oba tokeny (viz sekce výše)
• použít device flow, ale počítat s platností tokenu jen 24 hodin a bez možnosti tichého refreshe

Pro oficiální CLI se dá základní funkčnost ověřit samostatně:

higgsfield auth login
higgsfield model list
higgsfield generate create nano_banana_2 --prompt "test image" --wait

Příznak:

The OAuth 2.0 Client is not allowed to request scope 'openid'.

Význam: OpenCode vytvořil nebo použil OAuth klienta, který nemá povolený scope openid, ale autorizační URL tento scope obsahuje.

Rychlé řešení: Nepokračovat laděním API key/API secret. U oficiálního Higgsfield MCP jde o OAuth. Pokud OpenCode OAuth stále selhává, použít token z Claude Code jako Bearer header. Alternativně lze použít device flow, ale získaný token má jen 24hodinovou platnost a bez refresh tokenu. Pokud není nutné MCP rozhraní, zvážit oficiální Higgsfield CLI a případně Higgsfield AI Skills.

Příznak:

The 'redirect_uri' parameter does not match any of the OAuth 2.0 Client's pre-registered redirect urls.

Význam: Použitý OAuth klient má předregistrovaný jiný callback než ten, který posílá OpenCode. V mém případě Claude Code používal http://localhost:65498/callback, zatímco OpenCode používal http://127.0.0.1:19876/mcp/oauth/callback.

Rychlé řešení: Nepoužívat Claude Code clientId přímo v OpenCode, pokud nejde zároveň změnit callback na předregistrovanou hodnotu. Použít hotový token přes Bearer header, případně device flow bez redirect URI.

Příznak: autentizace v prohlížeči proběhne, ale Claude Code v kontejneru token nedostane.

Význam: Port callbacku není dostupný z hostitelského prohlížeče do Docker kontejneru.

Rychlé řešení: publikovat port 65498 z kontejneru na 127.0.0.1:65498 na hostu a OAuth zopakovat.

Příznak:

Session expired
Not authenticated

Význam: CLI token expiroval nebo není uložené platné přihlášení.

Rychlé řešení:

higgsfield auth login

Příznak:

Unknown model "..."

Význam: použitý název modelu není v aktuálním katalogu CLI.

Rychlé řešení:

higgsfield model list

• Token nikdy neukládat přímo do opencode.json.
• Soubory higgsfield.token a higgsfield_refresh.token držet mimo git a nastavit jim práva jen pro uživatele (chmod 600).
• Token v článku, logu ani chatu nevypisovat.
• Device flow token má podle testu platnost 24 hodin a neobsahuje refresh token.
• Refresh token může být zneplatněn ze strany Higgsfield (změna hesla, odvolání přístupu) – v takovém případě je nutné provést nový OAuth flow v Claude Code.
• U lokálních wrapperů nad Higgsfield API neukládat API key/API secret přímo do konfigurace; v OpenCode používat {file:…} a soubory držet mimo git.
• Při použití CLI a skills neukládat tokeny ani výstupy s citlivými URL do repozitáře. Pokud se používá –json v automatizaci, logovat jen nezbytné části odpovědi.

Claude Code fungoval, protože použil předregistrovaný OAuth flow a callback localhost:65498. V Dockeru bylo nutné tento port publikovat na hosta. OpenCode v mém prostředí narazil na OAuth problémy se scope openid a redirect_uri. Device flow přes fnf-device-auth.higgsfield.ai funguje bez redirect URI, ale vrací token jen na 24 hodin bez refresh tokenu. Prakticky nejlepší workaround pro remote MCP byl zkopírovat Higgsfield access token i refresh token z Claude Code credentials, uložit je do ~/.config/opencode/higgsfield.token a higgsfield_refresh.token a v OpenCode posílat Authorization: Bearer {file:./higgsfield.token} s oauth: false. Access token vyprší za 24 hodin – pro automatické obnovení slouží refresh skript, který volá Higgsfield OAuth endpoint bez prohlížeče, a cron ho spouští každých 20 hodin. Vedle toho je dnes důležitá oficiální cesta přes Higgsfield CLI a Higgsfield AI Skills; neoficiální lokální MCP wrappery nad API key/API secret dávají smysl už jen jako fallback, pokud je potřeba lokální MCP server a oficiální cesty nestačí.

• Higgsfield MCP – oficiální stránka
• Higgsfield MCP endpoint
• Higgsfield CLI – oficiální repozitář
• Higgsfield AI Skills – oficiální repozitář
• Higgsfield OAuth protected resource discovery
• Higgsfield device auth OpenAPI schema
• geopopos/higgsfield_ai_mcp
• geopopos/geo_higgsfield_ai_mcp
• Gemini MCP v OpenCode