Higgsfield MCP v Claude Code a OpenCode [Wiki]

Tato stránka je pouze pro čtení. Můžete si pouze prohlédnout zdrojový kód, ale ne ho měnit. Zeptejte se správce, pokud si myslíte, že něco není v pořádku.
====== Higgsfield MCP v Claude Code a OpenCode ======

//Vytvořeno: **2.5.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://higgsfield.ai/mcp|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|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: [[https://github.com/higgsfield-ai/cli|Higgsfield CLI]] pro terminálové použití a [[https://github.com/higgsfield-ai/skills|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.

===== Výchozí stav =====

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

===== Oficiální Higgsfield CLI =====

[[https://github.com/higgsfield-ai/cli|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.

==== Instalace ====

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

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

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

macOS / Linux přes Homebrew:

<code bash>
brew install higgsfield-ai/tap/higgsfield
</code>

Cross-platform instalace přes npm:

<code bash>
npm install -g @higgsfield/cli
</code>

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

<code bash>
higgsfield auth login
</code>

==== Základní použití ====

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

<code bash>
higgsfield generate create nano_banana_2 --prompt "a quiet beach at sunrise" --wait
</code>

Příklad pro Nano Banana Pro:

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

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

<code bash>
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
</code>

==== Hlavní příkazy ====

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:

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

==== Vztah k MCP integraci ====

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

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

===== Oficiální Higgsfield AI Skills =====

[[https://github.com/higgsfield-ai/skills|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.

==== Instalace skills ====

Doporučená cross-agent instalace:

<code bash>
npx skills add higgsfield-ai/skills
</code>

Alternativa přes GitHub CLI 2.90+:

<code bash>
gh skill install higgsfield-ai/skills
</code>

Instalace přes Claude Code marketplace:

<code>
/plugin marketplace add higgsfield-ai/skills
/plugin install higgsfield@higgsfield
</code>

Fallback přes clone repozitáře:

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

==== Dostupné skills ====

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

^ Skill ^ Vyvolání ^ Účel ^
| ''higgsfield-generate'' | ''/higgsfield:generate'' | Generování obrázků a videí přes 30+ modelů, Marketing Studio pro branded ads a Virality Predictor pro scoring hotových videí. |
| ''higgsfield-soul-id'' | ''/higgsfield:soul-id'' | Trénování Soul Character – opakovaně použitelné face-faithful identity. Výstupem je ''reference_id'' pro Soul-aware generování. |
| ''higgsfield-product-photoshoot'' | ''/higgsfield:product-photoshoot'' | Produktové fotky s prompt enhancementem a režimy jako studio, lifestyle, hero banner, social carousel, ad creative pack nebo virtual try-on. |
| ''higgsfield-marketplace-cards'' | ''/higgsfield:marketplace-cards'' | Marketplace produktové karty: hlavní produktový obrázek, sekundární obrázky a A+ style moduly. |

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.

==== Kdy použít skills místo přímého MCP ====

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.

===== Claude Code =====

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

<code bash>
claude mcp add --transport http higgsfield https://mcp.higgsfield.ai/mcp
</code>

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

<code json>
"higgsfield": {
  "type": "http",
  "url": "https://mcp.higgsfield.ai/mcp"
}
</code>

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.

==== Docker a callback port 65498 ====

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

<code>
http://localhost:65498/callback
</code>

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:

<code bash>
docker run -p 127.0.0.1:65498:65498 ...
</code>

Nebo v ''docker-compose.yml'':

<code yaml>
ports:
  - "127.0.0.1:65498:65498"
</code>

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

===== OpenCode: první pokus přes OAuth =====

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

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

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

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

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

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

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

===== Proč Claude Code fungoval a OpenCode ne =====

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:

<code>
http://127.0.0.1:19876/mcp/oauth/callback
</code>

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

<code>
{"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."}
</code>

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čí.

===== Co nezabralo =====

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.

===== Alternativní funkční cesta: device flow pro OpenCode =====

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.

[[https://mcp.higgsfield.ai/.well-known/oauth-protected-resource|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 [[https://fnf-device-auth.higgsfield.ai/openapi.json|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''

==== Ruční spuštění device flow ====

Získání device kódu:

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

Odpověď má tvar:

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

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:

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

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

<code json>
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 86400
}
</code>

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

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

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

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

==== Nevýhoda device flow ====

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

<code>
"expires_in": 86400
</code>

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í.

===== Preferovaný workaround: token z Claude Code pro OpenCode =====

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

  - vytáhnout Higgsfield access token a refresh token z Claude Code credentials
  - uložit je do souborů pro OpenCode
  - 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 [[#automaticka_obnova_tokenu_pres_refresh_token|Automatická obnova tokenu]] níže.

Token se nachází v souboru:

<code>
~/.claude/.credentials.json
</code>

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:

<code python>
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")
</code>

OpenCode konfigurace pak vypadá takto:

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

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.

===== Automatická obnova tokenu přes refresh token =====

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).

==== Refresh skript ====

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

<code bash>
#!/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"
</code>

<code bash>
chmod +x ~/.config/opencode/refresh-higgsfield-token.sh
</code>

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

<code bash>
~/.config/opencode/refresh-higgsfield-token.sh
</code>

==== Nastavení cronu na Alpine / busybox ====

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:

<code bash>
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>
</code>

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ěží:

<code bash>
sudo crond -b -l 8
</code>

==== Automatický start crond po restartu (Alpine / OpenRC) ====

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

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

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

===== Okrajová alternativa: neoficiální lokální MCP servery nad API key/API secret =====

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:

  * [[https://github.com/geopopos/higgsfield_ai_mcp|geopopos/higgsfield_ai_mcp]]
  * [[https://github.com/geopopos/geo_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''.

==== Rozdíl mezi oběma repozitáři ====

^ Oblast ^ ''higgsfield_ai_mcp'' ^ ''geo_higgsfield_ai_mcp'' ^
| Zaměření | Jednodušší MCP server pro základní image/video workflow. | Širší MCP server s více parametry a více typy nástrojů. |
| Framework | FastMCP. | Oficiální low-level ''mcp'' SDK. |
| Credentials | ''HF_API_KEY'' a ''HF_SECRET''. | ''HIGGSFIELD_API_KEY'' a ''HIGGSFIELD_SECRET''. |
| Instalace podle README | Clone repozitáře a instalace závislostí přes ''pip install -r requirements.txt'' nebo Poetry. | Deklaruje instalaci přes ''pip install higgsfield-mcp'' nebo instalaci ze zdrojů. |
| Nástroje | Jednodušší názvy jako ''generate_image'', ''generate_video'', ''get_generation_status'', ''create_character'', ''list_characters''. | Explicitnější názvy jako ''generate_image_soul'', ''generate_video_dop'', ''generate_speech_video'', ''get_job_status'', ''get_character'', ''delete_character''. |
| Parametry | Méně voleb, rychlejší na pochopení. | Více voleb: rozměry, batch size, seed, reference image, webhooky, motion strength, start/end frame. |
| Video | Image-to-video přes DoP/motion preset. | Image-to-video přes DoP, motions array, end frame. |
| Speech/talking head | V kódu se objevuje ''generate_talking_head''. | README popisuje ''generate_speech_video''. |
| Character management | Vytvoření a listování character references. | Vytvoření, načtení i mazání character references. |
| Resources/tools | Má MCP resources jako ''higgsfield%%://%%styles'', ''higgsfield%%://%%motions'', ''higgsfield%%://%%characters''. | Víc věcí řeší přes tools, například ''get_soul_styles'' a ''get_motions''. |

==== Kdy dává smysl který projekt ====

''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.

==== Důležitý konflikt názvů ====

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

<code>
higgsfield_mcp
higgsfield-mcp
</code>

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.

==== Princip konfigurace v OpenCode ====

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:

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

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'':

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

==== Výhody a nevýhody lokálních wrapperů ====

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

===== Ověření =====

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

Základní kontrola:

<code bash>
opencode mcp list
</code>

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ě:

<code bash>
higgsfield auth login
higgsfield model list
higgsfield generate create nano_banana_2 --prompt "test image" --wait
</code>

===== Rychlý troubleshooting pro budoucí řešení =====

==== Chyba: scope openid není povolený ====

Příznak:

<code>
The OAuth 2.0 Client is not allowed to request scope 'openid'.
</code>

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.

==== Chyba: redirect_uri nesedí ====

Příznak:

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

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.

==== Claude Code auth link se otevře, ale callback neprojde ====

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.

==== CLI hlásí Session expired nebo Not authenticated ====

Příznak:

<code>
Session expired
Not authenticated
</code>

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

Rychlé řešení:

<code bash>
higgsfield auth login
</code>

==== CLI nezná model ====

Příznak:

<code>
Unknown model "..."
</code>

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

Rychlé řešení:

<code bash>
higgsfield model list
</code>

===== Poznámky k bezpečnosti =====

  * 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.

===== Shrnutí =====

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čí.

===== Zdroje =====

  * [[https://higgsfield.ai/mcp|Higgsfield MCP – oficiální stránka]]
  * [[https://mcp.higgsfield.ai/mcp|Higgsfield MCP endpoint]]
  * [[https://github.com/higgsfield-ai/cli|Higgsfield CLI – oficiální repozitář]]
  * [[https://github.com/higgsfield-ai/skills|Higgsfield AI Skills – oficiální repozitář]]
  * [[https://mcp.higgsfield.ai/.well-known/oauth-protected-resource|Higgsfield OAuth protected resource discovery]]
  * [[https://fnf-device-auth.higgsfield.ai/openapi.json|Higgsfield device auth OpenAPI schema]]
  * [[https://github.com/geopopos/higgsfield_ai_mcp|geopopos/higgsfield_ai_mcp]]
  * [[https://github.com/geopopos/geo_higgsfield_ai_mcp|geopopos/geo_higgsfield_ai_mcp]]
  * [[ai:mcp:servery:gemini-mcp|Gemini MCP v OpenCode]]