====== 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 oficiálního remote MCP existují i neoficiální lokální MCP servery nad API key/API secret; ty jsou popsané níže jako jiná architektonická cesta.

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

===== 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í cesta: lokální MCP servery nad API key/API secret =====

Vedle oficiálního remote endpointu 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. Tím se dá obejít problém OpenCode OAuth flow, ale je to jiná integrace než oficiální Higgsfield MCP.

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
  * mohou pokrývat jen část funkcí oficiálního MCP konektoru
  * 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

===== 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. Pro běžné používání OpenCode je to příliš krátké, protože by bylo nutné device flow opakovat každý den nebo řešit automatické obnovování. Proto jsem se po testu vrátil k tokenu převzatému z Claude Code credentials, který byl v daném setupu praktičtější.

===== 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 z Claude Code credentials
  - uložit ho do souboru pro OpenCode
  - v OpenCode vypnout OAuth flow a posílat token jako statický Bearer header

Token se nachází v souboru:

<code>
/home/ubuntu/.claude/.credentials.json
</code>

V sekci ''mcpOAuth'' je položka pro Higgsfield. Token se dá bezpečně zkopírovat do samostatného souboru bez vypisování tokenu do terminálu:

<code python>
import json
from pathlib import Path

credentials_path = Path("/home/ubuntu/.claude/.credentials.json")
target_path = Path("/home/ubuntu/.config/opencode/higgsfield.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":
        token = item["accessToken"]
        break
else:
    raise SystemExit("Higgsfield token nebyl v Claude Code credentials nalezen")

target_path.write_text(token.strip() + "\n")
target_path.chmod(0o600)
</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>

Soubor ''higgsfield.token'' je relativní k adresáři s ''opencode.json'', tedy v tomto případě:

<code>
/home/ubuntu/.config/opencode/higgsfield.token
</code>

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

===== 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. Pak jsou dvě možnosti:

  * znovu provést přihlášení v Claude Code přes ''/mcp'' a zkopírovat nový ''accessToken'' do ''higgsfield.token''
  * použít device flow, ale počítat s platností tokenu jen 24 hodin

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

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

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

  * Token nikdy neukládat přímo do ''opencode.json''.
  * Soubor ''higgsfield.token'' držet mimo git a nastavit mu práva jen pro uživatele.
  * Token v článku, logu ani chatu nevypisovat.
  * Device flow token má podle testu platnost 24 hodin, takže se rychleji stane neplatným.
  * Pokud token expiruje nebo je kompromitovaný, znovu se přihlásit přes Claude Code nebo spustit device flow a token obnovit.
  * 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.

===== 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. Prakticky nejlepší workaround byl zkopírovat Higgsfield access token z Claude Code credentials, uložit ho do ''~/.config/opencode/higgsfield.token'' a v OpenCode posílat ''Authorization: Bearer {file:./higgsfield.token}'' s ''oauth: false''. Jako úplně jiná cesta existují lokální komunitní MCP servery nad API key/API secret, hlavně ''higgsfield_ai_mcp'' a ''geo_higgsfield_ai_mcp'', ale ty nejsou totéž co oficiální Higgsfield remote MCP endpoint.

===== Zdroje =====

  * [[https://higgsfield.ai/mcp|Higgsfield MCP – oficiální stránka]]
  * [[https://mcp.higgsfield.ai/mcp|Higgsfield MCP endpoint]]
  * [[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:klienti:gemini-mcp|Gemini MCP v OpenCode]]