Higgsfield MCP v Claude Code a OpenCode

Vytvořeno: 2.5.2026 | Aktualizováno: 02.05.2026 08:18

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.

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.

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

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

Token se nachází v souboru:

/home/ubuntu/.claude/.credentials.json

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:

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)

OpenCode konfigurace pak vypadá takto:

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

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

/home/ubuntu/.config/opencode/higgsfield.token

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

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

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.

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.

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

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.

• Higgsfield MCP – oficiální stránka
• Higgsfield MCP endpoint
• Higgsfield OAuth protected resource discovery
• Higgsfield device auth OpenAPI schema
• Gemini MCP v OpenCode