Serveur MCP distant

fremforge exploite un serveur Model Context Protocol à l’adresse :

https://frem.sh/_app/mcp

Il donne à un assistant IA un accès en lecture aux données fremforge de votre organisation : résultats de sécurité, inventaire des composants, déploiements, accès aux paquets, politiques, consommation des runners et journaux CI. Il n’y a rien à installer. Le serveur est distant et utilise le transport Streamable HTTP.

Ce que sont les outils

Chaque outil correspond à une opération de l’API REST de fremforge, et un appel d’outil est cet appel REST effectué avec votre jeton. L’outil peut faire exactement ce que votre jeton peut faire via https://frem.sh/_app/api/v1, avec les mêmes scopes, les mêmes limites de débit et la même piste d’audit. Une réponse 403 de l’API REST revient sous forme d’erreur d’outil, avec la même explication.

• En lecture seule, à l’exception de quelques outils d’écriture. Les outils sont des opérations GET marquées readOnlyHint pour votre client. Quelques outils d’écriture nommés peuvent agir en votre nom, mais uniquement après que vous avez consenti à chacun lors de la connexion, et uniquement là où les propriétaires de votre organisation l’autorisent.
• 43 outils, par exemple whoami, explain_pull_request, list_events (le flux d’événements), list_merge_holds, list_sast_findings, list_dependency_findings, list_secret_findings, search_components, list_vulnerable_components, get_dependency_paths, list_repo_deployments, get_actions_run_logs, get_org_policy, get_package_access, get_org_settings (les réglages Active work, merge-hold, release-train, niveau de risque, connecteurs IA et fonctionnalités IA d’une organisation, avec ce que vous êtes autorisé à voir) et get_my_settings (vos propres options Active work). Votre client les liste tous, avec leur description, lorsqu’il se connecte.
• Non inclus : les dépôts Git, les tickets, le contenu des pull requests et les listes d’exécutions de workflows. Ils sont servis par l’API Forgejo à l’adresse https://frem.sh/api/v1, et non par l’API fremforge. La raison pour laquelle une pull request ne fusionne pas est en revanche incluse : voir Pourquoi une pull request ne fusionne pas.
• Les résultats volumineux sont coupés à 100 000 caractères, avec une mention qui le signale. Utilisez les arguments limit, cursor ou de filtrage de l’outil pour les restreindre.

Pourquoi une pull request ne fusionne pas

L’outil explain_pull_request explique pourquoi une pull request n’a pas été fusionnée. Il correspond à l’appel REST :

curl -sS https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/pulls/<number>/why \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

Il nécessite le scope findings:read. Avec un connecteur à connexion, l’accès en lecture au dépôt suffit.

La réponse s’appuie sur les mêmes faits que ceux qui décident de la fusion : l’état propre de la file de fusion, les contrôles requis sur le commit de tête, les approbations, l’armement ou non de la fusion automatique, les conflits, et la présence d’un ticket ouvert portant le label release-freeze dans le dépôt. Un assistant obtient ainsi une réponse unique au lieu de devoir la reconstituer à partir de la liste des contrôles.

{
  "repo": "acme/api",
  "number": 42,
  "state": "failed",
  "next_action": "update the branch from main and re-run \"code-build / build (pull_request)\"",
  "reasons": [
    {
      "code": "stale_base_check",
      "kind": "failure",
      "source": "pr",
      "check": "code-build / build (pull_request)",
      "detail": "Required check \"code-build / build (pull_request)\" failed on an old base: main has moved since it ran.",
      "next_action": "update the branch from main and re-run \"code-build / build (pull_request)\""
    },
    {
      "code": "not_armed",
      "kind": "info",
      "source": "pr",
      "detail": "Auto-merge is not armed.",
      "next_action": "arm auto-merge once the reasons above are cleared"
    }
  ],
  "queue": null,
  "checks": { "required": ["code-build / build (pull_request)", "fremforge/dep-scan"], "passed": 1, "pending": 0, "failed": 1 },
  "approvals": { "required": 1, "approved": 1, "waived": false },
  "armed": false,
  "incomplete": []
}

• state vaut mergeable, waiting, blocked, failed, merged ou closed.
• reasons sont listées avec les échecs en premier, puis les blocages, puis les attentes. Chaque raison comporte un code, un court detail et une next_action.
• Codes issus de la pull request :
  • required_check_failed et required_check_pending.
  • stale_base_check : un contrôle requis est passé au rouge, et la branche de base a bougé depuis le lancement du contrôle. Mettez la branche à jour et relancez le contrôle avant de chercher le problème.
  • approvals_missing : la next_action indique à qui demander.
  • conflict, draft, armed et not_armed.
• Code issu du dépôt : freeze.
• Codes issus de la file de fusion (source: "queue") : group_failed, pending_timeout, failing_checks, own_checks_timeout, conflict, draft, approvals, no_permission, protected_files, merge_style, renovate et agit. Un retrait de la file que l’explicateur ne reconnaît pas porte le code queue_removed.
• queue donne la position, la longueur et un délai estimé tant que la pull request est dans la file de fusion.
• incomplete nomme tout fait qui n’a pas pu être lu, par exemple freeze ou approvals. La réponse peut alors omettre une raison. Rien n’est deviné.

Pour la liste brute des contrôles d’une branche, d’un tag ou d’un commit, les connecteurs à connexion disposent aussi de get_commit_status, qui renvoie le statut combiné de Forgejo.

Jeton

Le serveur accepte un jeton d’API fremforge (ffp_…) comme jeton porteur. Créez-en un sur https://frem.sh/<org>/_admin/api-tokens avec Créer le jeton et donnez-lui les scopes de lecture des outils que vous voulez utiliser. La description de chaque outil indique le scope dont il a besoin, par exemple findings:read, components:read, policy:read ou runners:read.

Les autres identifiants sont refusés, y compris les jetons d’accès Git (jetons d’accès personnels Forgejo) et les jetons OAuth Forgejo. Avec un jeton d’API, les outils Forgejo (dépôts, pull requests, tickets) ne sont pas disponibles : ils nécessitent le connecteur à connexion.

Commencez par l’outil whoami. Il indique l’organisation et les scopes associés au jeton.

Claude Code

claude mcp add --transport http fremforge https://frem.sh/_app/mcp \
  --header "Authorization: Bearer ffp_<your-token>"

Ou dans .mcp.json :

{
  "mcpServers": {
    "fremforge": {
      "type": "http",
      "url": "https://frem.sh/_app/mcp",
      "headers": { "Authorization": "Bearer ${FREMFORGE_TOKEN}" }
    }
  }
}

Cursor

Dans ~/.cursor/mcp.json (ou .cursor/mcp.json dans un projet) :

{
  "mcpServers": {
    "fremforge": {
      "url": "https://frem.sh/_app/mcp",
      "headers": { "Authorization": "Bearer ffp_<your-token>" }
    }
  }
}

Se connecter plutôt qu’utiliser un jeton. Omettez headers, et Cursor vous connecte via OAuth. Sa documentation MCP indique que Cursor prend en charge OAuth pour les serveurs qui l’exigent :

{
  "mcpServers": {
    "fremforge": { "url": "https://frem.sh/_app/mcp" }
  }
}

Cursor s’enregistre lui-même auprès de frem.sh : vous n’avez besoin d’aucun identifiant client. Il ouvre ensuite frem.sh dans votre navigateur, où vous vous connectez et autorisez l’accès comme décrit dans Connexion et consentement. Une fois connecté, Cursor obtient aussi les outils Forgejo en lecture seule. L’application de bureau reçoit la connexion sur votre propre machine ; Cursor sur le web et Cursor Agents la reçoivent sur cursor.com. Pour arrêter, supprimez le serveur ou désactivez-le sous Customize, et retirez-le aussi sur frem.sh.

Mistral

Le Chat. Un administrateur ajoute un connecteur MCP personnalisé :

1. Server URL : https://frem.sh/_app/mcp
2. Authentification : HTTP Bearer Token, avec votre jeton ffp_….

Le Chat classe les outils en fonctions de lecture et d’écriture. Tous les outils fremforge sont en lecture seule.

API Agents et SDK. Transmettez le jeton dans un en-tête. Dans le SDK Python, passez à MCPClientStreamableHTTP un StreamableHTTPServerParams(url="https://frem.sh/_app/mcp", headers={"Authorization": "Bearer ffp_…"}). Lorsque vous enregistrez un connecteur Studio (POST /v1/connectors), mettez le même en-tête dans headers.

Le Chat peut aussi vous connecter via OAuth plutôt qu’avec un jeton : voir Le Chat.

Connecteurs avec connexion : claude.ai, ChatGPT, Le Chat

Les applications de chat qui ajoutent un serveur MCP en tant que connecteur vous connectent via OAuth plutôt qu’avec un jeton. fremforge est le serveur d’autorisation de https://frem.sh/_app/mcp. Il prend en charge les Client ID Metadata Documents : un connecteur qui s’identifie par un document publié n’a besoin d’aucun enregistrement. Il prend aussi en charge l’enregistrement dynamique des clients, pour les connecteurs qui s’enregistrent eux-mêmes. Vous n’avez jamais à saisir d’identifiant ni de secret client.

Connexion et consentement

Le connecteur ouvre frem.sh dans votre navigateur. La suite est la même pour tous les connecteurs :

1. Connectez-vous à frem.sh comme d’habitude, avec l’authentification unique de votre organisation et le second facteur lorsqu’ils s’appliquent. Si vous êtes déjà connecté, cette étape est sautée.
2. La page de consentement de fremforge affiche le nom du connecteur, l’adresse vers laquelle il vous renverra et ce qu’il peut faire : lire, en votre nom, les données fremforge et les dépôts que vous pouvez lire. Si le connecteur s’est identifié par un document de métadonnées, la page affiche l’adresse complète de ce document. fremforge n’a pas vérifié le nom : n’autorisez l’accès que si c’est vous qui ajoutez le connecteur.
3. Choisissez Autoriser. Vous revenez dans l’application de chat, et le connecteur apparaît comme connecté.

Un assistant connecté peut utiliser les outils ci-dessus, plus des outils Forgejo en lecture seule : list_repos, get_repo, get_repo_tree, get_file_contents, list_branches, list_commits, get_commit, get_commit_diff, get_commit_status, list_pull_requests, get_pull_request, get_pull_request_diff, list_pull_request_files, list_pull_request_reviews, list_issues, get_issue, list_issue_comments, list_workflow_runs, get_workflow_run et list_workflow_jobs. Il ne peut rien modifier.

Il a exactement l’accès que vous avez via l’API. Les outils d’organisation répondent pour les organisations dont vous êtes propriétaire, et en lecture seule là où vous êtes auditeur. Les outils Forgejo répondent pour les dépôts que Forgejo vous laisse lire. La liste d’IP autorisées de votre organisation s’applique au connecteur comme à vous.

Le connecteur agit en votre nom et n’a pas d’identité propre. Un événement d’audit écrit par ses appels vous désigne comme actor, avec le connecteur en détail : fields.agent vaut mcp-client:<client id>. Le journal d’audit de l’administration affiche ces événements avec une pastille via un agent.

Le connecteur ne reçoit jamais votre mot de passe frem.sh ni vos jetons. Son propre accès dure une heure à la fois et se renouvelle en arrière-plan.

claude.ai

Les connecteurs personnalisés fonctionnent dans Claude sur le web, dans Claude Desktop et dans Cowork. Les formules gratuites autorisent un connecteur personnalisé. Le guide des connecteurs personnalisés de Claude donne la marche à suivre à jour :

1. Pro et Max : allez dans Customize → Connectors, choisissez + Add, puis Add custom connector. Team et Enterprise : un propriétaire va dans Organization settings → Connectors, choisit Add, puis Custom → Web. Les membres trouvent ensuite le connecteur sous Customize → Connectors et choisissent Connect.
2. Donnez-lui un nom, par exemple fremforge, et saisissez l’URL du serveur https://frem.sh/_app/mcp.
3. Pour le client OAuth, conservez Use Claude’s published identity. Register automatically fonctionne aussi. Laissez les en-têtes de requête vides.
4. Choisissez Add, puis connectez-vous et autorisez l’accès comme décrit dans Connexion et consentement.

Pour l’utiliser, choisissez + dans une conversation, puis Connectors, et activez fremforge pour cette conversation. Pour le supprimer, utilisez Remove ou le menu à côté du connecteur sur la même page, puis retirez-le aussi sur frem.sh.

ChatGPT

Dans ChatGPT, les serveurs MCP personnalisés s’appellent des plugins ou des apps. En ajouter un nécessite le mode développeur, et sur les formules Business, Enterprise et Edu, un administrateur de l’espace de travail peut devoir l’autoriser. Le guide d’OpenAI pour connecter un serveur MCP à ChatGPT donne la marche à suivre à jour :

1. Ouvrez ChatGPT Plugins, choisissez +, puis Add custom MCP server.
2. Saisissez un nom et une description. Sous Connection, choisissez Public endpoint et saisissez https://frem.sh/_app/mcp.
3. Pour l’authentification, choisissez OAuth. ChatGPT trouve la connexion de frem.sh à partir du serveur ; aucun identifiant client n’est donc nécessaire. Confirmez l’avertissement de risque et choisissez Create as a plugin.
4. Connectez-vous et autorisez l’accès comme décrit dans Connexion et consentement.

ChatGPT affiche les outils qu’il a trouvés. Pour les utiliser, tapez @ dans une nouvelle conversation et choisissez le plugin. Pour le supprimer, déconnectez-le ou supprimez-le dans les réglages d’applications de ChatGPT, puis retirez-le aussi sur frem.sh.

Le Chat

Dans Le Chat, c’est un administrateur qui ajoute les connecteurs personnalisés. Sur les formules Free, Pro et Student, le titulaire du compte est l’administrateur. La documentation des connecteurs MCP de Mistral donne la marche à suivre à jour :

1. Ouvrez Connectors, choisissez + Add Connector et passez à l’onglet Custom MCP Connector.
2. Saisissez un nom de connecteur sans espaces, par exemple fremforge, et l’URL du serveur https://frem.sh/_app/mcp.
3. Choisissez Connect. Le Chat détecte OAuth 2.1 et s’enregistre lui-même.
4. Connectez-vous et autorisez l’accès comme décrit dans Connexion et consentement.

Chaque utilisateur peut pré-approuver des fonctions sous Connectors → My Connectors, dans l’onglet Functions du connecteur. Sinon, Le Chat demande confirmation avant chaque appel. Toutes les fonctions fremforge sont en lecture seule. Pour ne plus l’utiliser, supprimez-le sur la page Connectors et retirez-le aussi sur frem.sh. Le Chat accepte aussi un jeton ffp_ comme jeton porteur HTTP au lieu de la connexion, comme dans Mistral ci-dessus.

Applications de bureau et redirections

Un client de bureau ou en ligne de commande qui se connecte via le navigateur doit récupérer le code sur le même appareil. fremforge accepte pour cela deux types de redirection :

• Boucle locale : http://127.0.0.1/…, http://[::1]/… ou http://localhost/…. Le port n’est pas pris en compte lors de la comparaison, si bien qu’un client peut écouter sur n’importe quel port libre (RFC 8252, section 7.3). Claude Code et l’application de bureau Cursor fonctionnent ainsi.
• Schémas d’application, comme cursor://…, vscode://… ou com.example.app:/callback, pour les clients sans secret client. Ils doivent correspondre exactement, port compris. La page de consentement nomme le schéma et avertit que n’importe quelle application installée peut en revendiquer un : n’autorisez l’accès que pour une application que vous connectez vous-même.

Certains schémas ne sont jamais acceptés comme redirection, quelle que soit leur casse :

• les schémas qu’un navigateur ou le système d’exploitation traite comme du contenu ou de la navigation : javascript, data, file, blob, ftp, about, ws, wss, vbscript, view-source, chrome, chrome-extension, moz-extension et intent ;
• les noms propres à fremforge : fremforge, frem et sh.frem ;
• http sur toute adresse autre qu’une boucle locale.

PKCE est obligatoire dans tous les cas.

Bloquer les connecteurs pour une organisation

Les connecteurs sont autorisés par défaut. Un propriétaire peut les bloquer sous Administration de l’organisation → Sécurité → Connecteurs IA, ou avec PUT /orgs/{org}/policy et {"ai_connectors": {"access": "blocked"}}. Tant qu’ils sont bloqués, chaque appel de connecteur portant sur les données de cette organisation, y compris ses dépôts, est refusé avec 403. Les jetons d’API ne sont pas concernés. Chaque changement est consigné dans le journal d’audit sous tenant.ai_connectors.blocked ou tenant.ai_connectors.allowed.

Retirer un connecteur

Retirer un connecteur met fin à toutes ses sessions d’un coup. Listez vos connecteurs, puis supprimez celui à retirer, avec un identifiant qui porte votre identité, comme celui qu’enregistre fremforge auth login :

curl -sS https://frem.sh/_app/api/v1/users/me/connector-grants -H "Authorization: Bearer $TOKEN"
curl -sS -X DELETE https://frem.sh/_app/api/v1/users/me/connector-grants/<id> -H "Authorization: Bearer $TOKEN"

Pour le reconnecter, ajoutez-le à nouveau ; votre consentement vous sera de nouveau demandé. Révoquer l’application de connecteur fremforge sous Applications OAuth2 autorisées sur frem.sh/user/settings/applications, ou la désactivation de votre compte, met aussi fin à tous vos connecteurs dès la prochaine utilisation de l’un d’eux.

Vérifier la connexion

curl -sS https://frem.sh/_app/mcp \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

Erreurs

Souveraineté

Le fournisseur de votre assistant reçoit ce que renvoient les outils, de la même façon qu’il reçoit les fichiers que vous ouvrez. fremforge n’envoie vos données à aucun fournisseur d’IA. Le serveur MCP fait partie de l’API fremforge et s’exécute sur la même plateforme européenne.