MCP

Foca MCP permet à un client IA de consulter votre solde de crédits, d’agrandir une image depuis une URL HTTPS et de récupérer le résultat. Il utilise le moteur avancé physics et partage les crédits et les droits de votre compte sur le site. Chaque création de tâche traite une image. La sortie par défaut est 2K, pour 15 crédits par image.

Connecter votre client

La création de tâches MCP et de nouvelles clés API nécessite un abonnement payant actif ou un achat réussi de pack de crédits. Un achat de pack réussi conserve cette éligibilité même si son solde atteint zéro. Les crédits offerts à l’inscription ne donnent pas accès à MCP. Un compte avec uniquement un pack peut créer des tâches 2K ; les résolutions supérieures nécessitent l’abonnement actif correspondant.

1. Connectez-vous et ouvrez les paramètres des clés API pour créer une clé.
2. Enregistrez-la dès son affichage. La clé complète n’est affichée qu’une fois.
3. Choisissez votre client ci-dessous. Le point d’accès utilise Streamable HTTP avec Authorization: Bearer YOUR_API_KEY.

{
  "mcpServers": {
    "foca": {
      "url": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "foca-api-key",
      "description": "Foca API key",
      "password": true
    }
  ],
  "servers": {
    "foca": {
      "type": "http",
      "url": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:foca-api-key}"
      }
    }
  }
}

claude mcp add --transport http foca https://focaupscaler.com/api/mcp   --header 'Authorization: Bearer YOUR_API_KEY'

[mcp_servers.foca]
url = "https://focaupscaler.com/api/mcp"
bearer_token_env_var = "FOCA_API_KEY"

export FOCA_API_KEY='YOUR_API_KEY'

{
  "mcpServers": {
    "foca": {
      "serverUrl": "https://focaupscaler.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "foca": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.15.1",
        "https://focaupscaler.com/api/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${FOCA_AUTH_HEADER}"
      ],
      "env": {
        "FOCA_AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Les clés API agissent au nom de votre compte et peuvent dépenser ses crédits. Conservez-les dans les paramètres secrets du client et révoquez les clés inutilisées dans les paramètres des clés API. Ne les placez pas dans des URL, des prompts ou un dépôt de code. Les tâches et crédits appartiennent au compte qui a créé la clé.

Les actions « Lire dans ChatGPT » et « Lire dans Claude » ouvrent un prompt de lecture de ce guide public. Elles ne connectent pas MCP et n’autorisent pas l’accès au compte.

Crédits et accès par offre

Appelez get_upscale_info avant de soumettre une tâche. La valeur available indique les droits de votre offre ; le balance doit aussi couvrir le coût de la tâche. MCP et le site partagent le même solde. Consultez les offres et crédits pour changer d’offre ou ajouter des crédits.

Conditions sur les images

• Une URL HTTPS publique sur le port 443, sans identifiant, mot de passe ni en-tête d’authentification supplémentaire. Les adresses locales et les réseaux privés sont refusés.
• Un fichier JPEG, PNG ou WebP valide de 20 Mo maximum, soit 20 Mio ou 20 971 520 octets.
• Au maximum 64 millions de pixels en entrée (64 MP).
• Une URL signée temporaire est acceptée si elle reste valide pendant le téléchargement. Celui-ci est limité à 20 secondes et à trois redirections.

Un échec de téléchargement ou de validation de l’image ne crée pas de tâche et ne débite pas de crédits de traitement.

Exemples de requêtes JSON-RPC

Les clients MCP gèrent normalement l’initialisation et la découverte des outils. Pour examiner les requêtes directement, exécutez les exemples suivants dans la même session de terminal. Remplacez la clé API et l’URL d’exemple par vos propres valeurs.

Toutes les requêtes utilisent POST et les en-têtes ci-dessous. Ce point d’accès renvoie du JSON et fonctionne sans état : il n’émet pas d’identifiant de session et ne fournit pas de connexion SSE GET séparée. Les exemples utilisent la version 2025-11-25 du protocole ; le client doit reprendre la version négociée par initialize dans les requêtes suivantes.

export FOCA_API_KEY='YOUR_API_KEY'

foca_mcp() {
  curl --silent --show-error 'https://focaupscaler.com/api/mcp' \
    --header "Authorization: Bearer $FOCA_API_KEY" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json, text/event-stream' \
    --header 'MCP-Protocol-Version: 2025-11-25' \
    --data-binary @-
}

Initialisation et découverte des outils

Envoyez initialize, puis la notification notifications/initialized une fois l’initialisation réussie. La réponse identifie le serveur comme foca-upscaler et annonce sa capacité à fournir des outils.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "foca-example-client",
      "version": "1.0.0"
    }
  }
}
JSON

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
JSON

Récupérez les schémas des outils avec tools/list :

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
JSON

Le tableau result.tools contient get_upscale_info, upscale_image et get_upscale_task. Respectez le inputSchema de chaque outil ; les arguments supplémentaires sont refusés.

1. Consulter le compte avec get_upscale_info

Arguments : un objet vide, {}. Cette consultation ne consomme pas de crédits de traitement.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_upscale_info",
    "arguments": {}
  }
}
JSON

Exemple de result.structuredContent pour un compte ayant accès à toutes les résolutions :

{
  "engine": "physics",
  "balance": 200,
  "can_create_tasks": true,
  "tiers": [
    { "resolution_tier": 2, "credits": 15, "available": true },
    { "resolution_tier": 4, "credits": 30, "available": true },
    { "resolution_tier": 8, "credits": 60, "available": true },
    { "resolution_tier": 16, "credits": 120, "available": true }
  ],
  "max_file_size_bytes": 20971520,
  "formats": ["image/jpeg", "image/png", "image/webp"]
}

balance est le solde actuel. tiers indique le coût et les droits d’accès de chaque résolution. max_file_size_bytes et formats décrivent les fichiers acceptés. Les résultats contiennent aussi un élément texte content avec les mêmes données sérialisées en JSON ; les exemples montrent uniquement le structuredContent décodé.

can_create_tasks indique si le compte possède actuellement l’éligibilité payante MCP. Une clé API valide et non révoquée peut toujours appeler get_upscale_info et get_upscale_task après l’expiration d’un abonnement ; sans achat réussi de pack, can_create_tasks devient false et les nouvelles tâches sont refusées. Ce champ ne garantit ni un solde suffisant ni l’accès à toutes les résolutions.

2. Créer une tâche avec upscale_image

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "upscale_image",
    "arguments": {
      "image_url": "https://images.example.com/source.png",
      "resolution_tier": 2,
      "idempotency_key": "source-001-2k"
    }
  }
}
JSON

Une nouvelle tâche peut renvoyer le result.structuredContent suivant avant la fin du traitement :

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "pending",
  "credits_charged": 15,
  "credits_remaining": 185,
  "resolution_tier": 2
}

task_id est l’UUID à utiliser pour les consultations suivantes. La création est asynchrone ; le status peut déjà avoir progressé à la réception de la réponse. credits_charged enregistre le coût de la tâche. Consultez à nouveau get_upscale_info pour connaître votre solde actuel.

La création et la consultation d’une tâche renvoient credits_remaining, le solde actuel du compte au moment de la réponse. Une répétition idempotente donne le solde actuel, qui peut différer de celui observé juste après le débit initial.

3. Récupérer une tâche avec get_upscale_task

Le seul argument, obligatoire, est task_id : l’UUID renvoyé à la création. Seules les tâches du compte associé à la clé API sont accessibles. Remplacez l’UUID d’exemple par celui de votre tâche.

foca_mcp <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_upscale_task",
    "arguments": {
      "task_id": "00000000-0000-4000-8000-000000000001"
    }
  }
}
JSON

Une tâche terminée renvoie cette forme de result.structuredContent. L’URL et la date sont données à titre d’exemple :

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "status": "succeeded",
  "credits_charged": 15,
  "credits_remaining": 185,
  "resolution_tier": 2,
  "download_url": "https://downloads.example.com/result.png?signature=EXAMPLE",
  "expires_at": "2026-10-17T13:00:00.000Z"
}

Statuts et expiration des résultats

Espacez les appels à get_upscale_task et augmentez le délai en cas de limitation. Arrêtez lorsque le statut vaut succeeded ou failed. Le traitement continue sur le serveur ; la connexion MCP peut être fermée pendant ce temps.

Les liens de téléchargement sont temporaires. expires_at est une date ISO 8601 ; respectez la valeur réellement renvoyée. La durée par défaut est d’une heure, mais elle peut varier. Si seul le lien a expiré, consultez à nouveau la tâche pour obtenir un lien signé tant que le résultat est conservé.

Les résultats sont conservés 24 heures à compter de la création de la tâche. Au-delà, la consultation renvoie status: "failed" avec error_code: "RESULT_EXPIRED", ou TASK_NOT_FOUND si l’enregistrement a été supprimé. Téléchargez et conservez votre propre copie pendant ce délai.

Nouvelles tentatives et idempotence

Après un délai d’attente dépassé ou une réponse perdue, conservez les mêmes idempotency_key, image_url et resolution_tier. La répétition renvoie la tâche existante sans débiter à nouveau les crédits. La clé d’idempotence s’applique au compte, y compris aux appels effectués avec ses autres clés API.

Utilisez une nouvelle clé pour une autre URL ou résolution. Une clé réutilisée avec des paramètres différents provoque IDEMPOTENCY_CONFLICT. Ne changez pas de clé simplement parce qu’une réponse a été perdue : la tâche initiale peut déjà exister. Modifier les paramètres de requête d’une URL signée modifie aussi les paramètres de la demande.

Les enregistrements d’idempotence sont conservés au moins 30 jours, puis supprimés par le nettoyage quotidien. Après leur suppression, réutiliser une ancienne clé peut créer et facturer une nouvelle tâche. Ne relancez pas une ancienne création après cette période ; les résultats restent soumis à leur conservation distincte de 24 heures.

Erreurs et limites

Un échec métier met result.isError à true et fournit result.structuredContent.error.code ainsi qu’un message. Traitez le code plutôt que le texte du message. Les requêtes JSON-RPC et arguments de schéma invalides sont refusés par la couche protocolaire.

Les messages d’erreur sont renvoyés en anglais, quelle que soit la langue du client. En cas de solde insuffisant, result.structuredContent contient les détails ci-dessous. Utilisez required_credits et credits_remaining pour expliquer le manque, et upgrade_url pour ouvrir les tarifs.

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to create this task.",
    "required_credits": 15,
    "credits_remaining": 5,
    "upgrade_url": "https://focaupscaler.com/pricing"
  }
}

Chaque compte est limité à 60 requêtes MCP par minute, dont au maximum cinq tentatives de création par minute. La couche HTTP peut renvoyer 401 UNAUTHORIZED pour une clé absente, invalide ou révoquée ; 403 INVALID_ORIGIN pour un en-tête Origin refusé ; 429 RATE_LIMITED avec Retry-After: 60 ; ou 503 MCP_UNAVAILABLE si le service est indisponible. Utilisez un client MCP distant capable d’envoyer les en-têtes d’autorisation requis.

Dans les paramètres des clés API, POST /api/mcp/keys renvoie HTTP 403 PAID_ACCESS_REQUIRED sans éligibilité payante et HTTP 503 MCP_UNAVAILABLE si la création est temporairement indisponible. La consultation et la révocation des clés existantes restent possibles. Une clé Bearer MCP invalide reçoit toujours HTTP 401, jamais une réponse d’outil réussie.

Tester la connexion

Après la connexion, envoyez ce prompt à votre client :

Utilise get_upscale_info de Foca pour afficher mon solde de crédits et les résolutions disponibles. Ne crée aucune tâche d’image.

Une réponse valide confirme la découverte des outils et l’authentification. Cette vérification en lecture seule ne consomme pas de crédits de traitement. Pour tester ensuite le traitement, fournissez votre propre URL HTTPS publique et demandez explicitement une résolution ; le coût indiqué s’applique.

Confidentialité et conditions

Consultez la politique de confidentialité et les conditions d’utilisation avant d’envoyer des images. Envoyez uniquement des images que vous êtes autorisé à traiter.