Externe MCP-server

fremforge draait een Model Context Protocol-server op:

https://frem.sh/_app/mcp

Daarmee krijgt een AI-assistent leestoegang tot de fremforge-gegevens van je organisatie: beveiligingsbevindingen, de componenteninventaris, deployments, pakkettoegang, beleid, runnergebruik en CI-logs. Er hoeft niets geïnstalleerd te worden. De server draait extern en spreekt het transport Streamable HTTP.

Wat de tools zijn

Elke tool is één bewerking van de REST API van fremforge, en een toolaanroep is die REST-aanroep, gedaan met jouw token. De tool kan precies wat je token via https://frem.sh/_app/api/v1 kan, met dezelfde scopes, rate limits en audittrail. Een 403 van de REST API komt terug als toolfout met dezelfde uitleg.

• Alleen-lezen, op een paar schrijftools na. De tools zijn GET-bewerkingen die voor je client met readOnlyHint zijn gemarkeerd. Een paar benoemde schrijftools kunnen als jou handelen, maar alleen nadat je bij het inloggen voor elk daarvan toestemming hebt gegeven, en alleen waar de eigenaren van je organisatie dat toestaan.
• 43 tools, bijvoorbeeld whoami, explain_pull_request, list_events (de gebeurtenisfeed), 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 (de instellingen voor Active work, merge-holds, release-trains, risiconiveaus, AI-koppelingen en AI-functies van een organisatie, met wat jij mag zien) en get_my_settings (je eigen schakelaars voor Active work). Je client toont ze allemaal, met beschrijvingen, zodra hij verbinding maakt.
• Niet inbegrepen: Git-repository’s, issues, de inhoud van pull requests en lijsten met workflowruns. Die worden geleverd door de Forgejo-API op https://frem.sh/api/v1, niet door de fremforge-API. Waarom een pull request niet wordt gemerged, is wel inbegrepen: zie Waarom een pull request niet wordt gemerged.
• Grote resultaten worden afgekapt op 100.000 tekens, met een melding daarover. Gebruik de argumenten limit, cursor of de filters van de tool om ze in te perken.

Waarom een pull request niet wordt gemerged

De tool explain_pull_request geeft antwoord op de vraag waarom een pull request niet is gemerged. Het is de REST-aanroep:

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

Die heeft de scope findings:read nodig. Met een koppeling via inloggen is leestoegang tot de repository voldoende.

Het antwoord leest dezelfde feiten die over de merge beslissen: de eigen status van de samenvoegwachtrij, de verplichte checks op de head-commit, goedkeuringen, of auto-merge is ingeschakeld, conflicten, en een open issue met het label release-freeze in de repository. Een assistent krijgt één antwoord in plaats van het zelf uit de lijst met checks te moeten samenstellen.

{
  "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 is een van mergeable, waiting, blocked, failed, merged of closed.
• reasons staan in de volgorde fouten, dan blokkades, dan wachttoestanden. Elke reden heeft een code, een korte detail en een next_action.
• Codes van de pull request:
  • required_check_failed en required_check_pending.
  • stale_base_check: een verplichte check is rood geworden en de basisbranch is verschoven sinds de check begon. Werk de branch bij en draai de check opnieuw voordat je gaat debuggen.
  • approvals_missing: de next_action noemt wie je moet vragen.
  • conflict, draft, armed en not_armed.
• Code van de repository: freeze.
• Codes van de samenvoegwachtrij (source: "queue"): group_failed, pending_timeout, failing_checks, own_checks_timeout, conflict, draft, approvals, no_permission, protected_files, merge_style, renovate en agit. Een verwijdering die de uitlegtool niet herkent, krijgt de code queue_removed.
• queue geeft de positie, de lengte en een verwachte tijd zolang de pull request in de samenvoegwachtrij staat.
• incomplete noemt elk feit dat niet kon worden gelezen, bijvoorbeeld freeze of approvals. Het antwoord kan dan een reden missen. Er wordt niets geraden.

Voor de kale lijst met checks van een willekeurige branch, tag of commit hebben koppelingen via inloggen ook get_commit_status, dat de gecombineerde status van Forgejo teruggeeft.

Token

De server accepteert een fremforge-API-token (ffp_…) als bearer-token. Maak er een aan op https://frem.sh/<org>/_admin/api-tokens met Token aanmaken en geef het de leesscopes voor de tools die je wilt gebruiken. De beschrijving van elke tool noemt de scope die hij nodig heeft, bijvoorbeeld findings:read, components:read, policy:read of runners:read.

Andere inloggegevens worden geweigerd, waaronder Git-toegangstokens (persoonlijke toegangstokens van Forgejo) en OAuth-tokens van Forgejo. Met een API-token zijn de Forgejo-tools (repository’s, pull requests, issues) niet beschikbaar: die vereisen de koppeling via inloggen.

Begin met de tool whoami. Die laat zien welke tenant en welke scopes het token heeft.

Claude Code

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

Of in .mcp.json:

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

Cursor

In ~/.cursor/mcp.json (of .cursor/mcp.json in een project):

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

Inloggen in plaats van een token. Laat headers weg, dan logt Cursor je in met OAuth. Volgens de MCP-documentatie van Cursor ondersteunt Cursor OAuth voor servers die dat vereisen:

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

Cursor registreert zichzelf bij frem.sh, dus je hebt geen client-ID nodig. Daarna opent het frem.sh in je browser, waar je inlogt en toegang verleent zoals beschreven in Inloggen en toestemming. Ingelogd krijgt Cursor ook de Forgejo-tools voor alleen-lezen. De desktopapp ontvangt het inloggen op je eigen machine; Cursor op het web en Cursor Agents ontvangen het op cursor.com. Wil je stoppen, verwijder de server dan of zet hem uit onder Customize, en trek hem ook in op frem.sh.

Mistral

Le Chat. Een beheerder voegt een eigen MCP-koppeling toe:

1. Server-URL: https://frem.sh/_app/mcp
2. Authenticatie: HTTP Bearer Token, met je ffp_…-token.

Le Chat deelt tools in als lees- of schrijffuncties. Alle fremforge-tools zijn alleen-lezen.

Agents-API en SDK. Geef het token mee als header. Geef in de Python-SDK MCPClientStreamableHTTP een StreamableHTTPServerParams(url="https://frem.sh/_app/mcp", headers={"Authorization": "Bearer ffp_…"}) mee. Registreer je een Studio-koppeling (POST /v1/connectors), zet dan dezelfde header in headers.

Le Chat kan je ook met OAuth laten inloggen in plaats van met een token: zie Le Chat.

Koppelingen met inloggen: claude.ai, ChatGPT, Le Chat

Chatapps die een MCP-server als koppeling (connector) toevoegen, laten je inloggen met OAuth in plaats van met een token. fremforge is de autorisatieserver voor https://frem.sh/_app/mcp. Het ondersteunt Client ID Metadata Documents, zodat een koppeling die zich identificeert met een gepubliceerd document geen registratie nodig heeft. Het ondersteunt ook dynamische clientregistratie voor koppelingen die zichzelf registreren. Je voert nooit een client-ID of client-secret in.

Inloggen en toestemming

De koppeling opent frem.sh in je browser. Wat volgt, is voor elke koppeling hetzelfde:

1. Log zoals gewoonlijk in bij frem.sh, met de single sign-on en de tweede factor van je organisatie waar die van toepassing zijn. Ben je al ingelogd, dan wordt deze stap overgeslagen.
2. De toestemmingspagina van fremforge toont de naam van de koppeling, het adres waarnaar je wordt teruggestuurd en wat de koppeling kan: als jou de fremforge-gegevens en repository’s lezen die jij mag lezen. Heeft de koppeling zich geïdentificeerd met een metadatadocument, dan toont de pagina het volledige adres van dat document. fremforge heeft de naam niet geverifieerd, dus sta het alleen toe als je de koppeling zelf toevoegt.
3. Kies Toestaan. Je keert terug naar de chatapp en de koppeling staat als verbonden.

Een verbonden assistent kan de tools hierboven gebruiken, plus de Forgejo-tools voor alleen-lezen: 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 en list_workflow_jobs. Hij kan niets wijzigen.

Hij heeft precies de toegang die jij via de API hebt. De organisatietools antwoorden voor de organisaties waarvan je eigenaar bent, en alleen-lezen waar je auditor bent. De Forgejo-tools antwoorden voor de repository’s die Forgejo je laat lezen. De IP-allowlist van je organisatie geldt voor de koppeling zoals voor jou.

De koppeling handelt namens jou en heeft geen eigen identiteit. Een auditgebeurtenis die door zijn aanroepen wordt geschreven, noemt jou als actor, met de koppeling als detail: fields.agent is mcp-client:<client id>. Het auditlog in het beheer toont zulke gebeurtenissen met een label via agent.

De koppeling krijgt nooit je frem.sh-wachtwoord of je tokens. Zijn eigen toegang geldt telkens een uur en wordt op de achtergrond vernieuwd.

claude.ai

Eigen koppelingen werken in Claude op het web, in Claude Desktop en in Cowork. Gratis abonnementen staan één eigen koppeling toe. De handleiding voor eigen koppelingen van Claude bevat de actuele stappen:

1. Pro en Max: ga naar Customize → Connectors, kies + Add en daarna Add custom connector. Team en Enterprise: een eigenaar gaat naar Organization settings → Connectors, kiest Add en daarna Custom → Web. Leden vinden de koppeling daarna onder Customize → Connectors en kiezen Verbinden.
2. Geef hem een naam, bijvoorbeeld fremforge, en vul de server-URL https://frem.sh/_app/mcp in.
3. Houd voor de OAuth-client Use Claude’s published identity aan. Register automatically werkt ook. Laat de request-headers leeg.
4. Kies Add, log daarna in en verleen toegang zoals beschreven in Inloggen en toestemming.

Om hem te gebruiken kies je in een chat +, dan Connectors, en zet je fremforge aan voor dat gesprek. Om hem te verwijderen gebruik je Remove of het menu naast de koppeling op dezelfde pagina, en trek je hem ook in op frem.sh.

ChatGPT

ChatGPT noemt eigen MCP-servers plug-ins of apps. Er een toevoegen vereist de ontwikkelaarsmodus, en bij Business-, Enterprise- en Edu-abonnementen moet een werkruimtebeheerder dat mogelijk toestaan. De handleiding van OpenAI voor het verbinden van een MCP-server met ChatGPT bevat de actuele stappen:

1. Open ChatGPT Plugins, kies + en daarna Add custom MCP server.
2. Vul een naam en beschrijving in. Kies onder Connection de optie Public endpoint en vul https://frem.sh/_app/mcp in.
3. Kies OAuth als authenticatie. ChatGPT vindt de inlog van frem.sh via de server, dus een client-ID is niet nodig. Bevestig de risicowaarschuwing en kies Create as a plugin.
4. Log in en verleen toegang zoals beschreven in Inloggen en toestemming.

ChatGPT toont de tools die het heeft gevonden. Om ze te gebruiken typ je @ in een nieuw gesprek en kies je de plug-in. Om hem te verwijderen koppel je hem los of verwijder je hem in de app-instellingen van ChatGPT, en trek je hem ook in op frem.sh.

Le Chat

In Le Chat voegt een beheerder eigen koppelingen toe. Bij Free-, Pro- en Student-abonnementen is de accounteigenaar de beheerder. De documentatie over MCP-koppelingen van Mistral bevat de actuele stappen:

1. Open Connectors, kies + Add Connector en ga naar het tabblad Custom MCP Connector.
2. Vul een naam voor de koppeling in zonder spaties, bijvoorbeeld fremforge, en de server-URL https://frem.sh/_app/mcp.
3. Kies Connect. Le Chat detecteert OAuth 2.1 en registreert zichzelf.
4. Log in en verleen toegang zoals beschreven in Inloggen en toestemming.

Elke gebruiker kan functies vooraf goedkeuren onder Connectors → My Connectors, op het tabblad Functions van de koppeling. Anders vraagt Le Chat vóór elke aanroep om bevestiging. Alle fremforge-functies zijn alleen-lezen. Wil je stoppen, verwijder hem dan op de pagina Connectors en trek hem ook in op frem.sh. Le Chat accepteert ook een ffp_-token als HTTP-bearer-token in plaats van inloggen, zoals bij Mistral hierboven.

Desktopapps en redirects

Een desktop- of command-line-client die via de browser inlogt, moet de code terugkrijgen op hetzelfde apparaat. fremforge accepteert daarvoor twee soorten redirects:

• Loopback: http://127.0.0.1/…, http://[::1]/… of http://localhost/…. De poort wordt bij het vergelijken genegeerd, zodat een client op elke vrije poort kan luisteren (RFC 8252, paragraaf 7.3). Claude Code en de desktopapp van Cursor werken zo.
• App-schema’s, zoals cursor://…, vscode://… of com.example.app:/callback, voor clients zonder client-secret. Die moeten exact overeenkomen, inclusief poort. De toestemmingspagina noemt het schema en waarschuwt dat elke geïnstalleerde app een schema kan claimen; sta het dus alleen toe voor een app die je zelf verbindt.

Sommige schema’s worden nooit als redirect geaccepteerd, ongeacht hoofdletters:

• schema’s die een browser of het besturingssysteem als inhoud of navigatie behandelt: javascript, data, file, blob, ftp, about, ws, wss, vbscript, view-source, chrome, chrome-extension, moz-extension en intent;
• de eigen namen van fremforge: fremforge, frem en sh.frem;
• http op iets anders dan een loopback-adres.

PKCE is in alle gevallen verplicht.

Koppelingen blokkeren voor een organisatie

Koppelingen zijn standaard toegestaan. Een eigenaar kan ze blokkeren onder Organisatiebeheer → Beveiliging → AI-koppelingen, of met PUT /orgs/{org}/policy en {"ai_connectors": {"access": "blocked"}}. Zolang ze geblokkeerd zijn, wordt elke aanroep van een koppeling naar de gegevens van die organisatie, inclusief haar repository’s, geweigerd met 403. API-tokens worden niet beïnvloed. Elke wijziging wordt in het auditlog vastgelegd als tenant.ai_connectors.blocked of tenant.ai_connectors.allowed.

Een koppeling intrekken

Een koppeling intrekken beëindigt in één keer al haar sessies. Vraag je koppelingen op en verwijder daarna degene die je wilt intrekken, met inloggegevens die jouw identiteit dragen, zoals die welke fremforge auth login opslaat:

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"

Om hem opnieuw te verbinden, voeg je hem opnieuw toe; er wordt dan opnieuw om je toestemming gevraagd. Het intrekken van de fremforge-koppelingsapplicatie onder Geautoriseerde OAuth2 applicaties op frem.sh/user/settings/applications, of een uitgeschakeld account, beëindigt ook al je koppelingen, de eerstvolgende keer dat er een wordt gebruikt.

De verbinding controleren

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":{}}}'

Foutmeldingen

Soevereiniteit

De leverancier van je assistent ontvangt wat de tools teruggeven, op dezelfde manier als hij de bestanden ontvangt die je opent. fremforge stuurt je gegevens niet naar een AI-leverancier. De MCP-server is onderdeel van de fremforge-API en draait op hetzelfde EU-platform.