Higgsfield MCP v Claude Code a OpenCode

Vytvořeno: 2.5.2026 | Aktualizováno: 04.05.2026 08:57

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

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.

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:

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

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.

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

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.

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

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

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