MCP-Server: ein gehosteter Browser für Coding-Agenten

Was MCP dir gibt

Der MCP-Server legt einen echten, gehosteten Browser in die Hände jedes MCP-fähigen Agenten — Claude Code, das Claude Agent SDK, Cursor und die übrigen. Hinter den Tools sitzt dieselbe Session-API, die auch die SDKs benutzen, mit denselben Sicherheitsgattern auf jeder Aktion und denselben drei geprüften Aufgaben-Ausgängen.

Er ist gehostet: Die Control Plane stellt den Server unter /v1/mcp über Streamable HTTP bereit, authentifiziert mit deinem API-Schlüssel im Authorization-Header. Installiert wird nichts. Die Tool-Liste ist auf das gefiltert, was dein Deployment tatsächlich kann, sodass einem Agenten nie ein Tool angeboten wird, das nur ablehnen würde.

Das Session-Handling bleibt absichtlich unspektakulär. Eine Session entsteht träge beim ersten Tool-Aufruf, der sie braucht, wird von jedem weiteren Aufruf wiederverwendet und beim Ende der Verbindung freigegeben — außer, eine Aufgabe läuft noch darauf; dann bleibt sie bis zu ihrer eigenen Frist bestehen, damit die Aufgabe fertig werden und abgefragt werden kann. Jedes Browser-Tool akzeptiert optional eine sessionId für die Fälle, in denen du zwei Seiten gleichzeitig bearbeiten willst.

Deinen Agenten verbinden

Der gehostete Endpunkt ist der empfohlene Weg: Trag ihn mit deinem Schlüssel im Header in die MCP-Konfiguration deines Agenten ein. Die stdio-Form startet das quelloffene Paket lokal per `npx` und passt zu Clients ohne HTTP-Transport oder zu einem selbst gehosteten Deployment.

{
  "mcpServers": {
    "browserberg": {
      "type": "http",
      "url": "https://browserberg.com/v1/mcp",
      "headers": { "Authorization": "Bearer bb_your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "browserberg": {
      "command": "npx",
      "args": ["-y", "@browserberg/mcp"],
      "env": { "BROWSERBERG_API_KEY": "bb_your_key_here" }
    }
  }
}

Die Browser-Tools

Die Inferenzkosten stehen pro Tool-Aufruf in der zweiten Spalte. Eine Seite lesen und Sessions verwalten kostet nichts; eine Aktion in Alltagssprache kostet einen Modellaufruf; eine delegierte Aufgabe mehrere.

Name	Typ	Beschreibung
`browser_navigate`	kein Modellaufruf	Öffnet eine URL als einfachen deterministischen Schritt; der übliche erste Zug.
`browser_observe`	standardmäßig kein Modellaufruf	Liest die Live-Seite und liefert bedienbare Kandidaten. Ohne Instruktion entsteht kein Modellaufruf; mit Instruktion filtert das Modell die Funde.
`browser_act`	ein Modellaufruf	Führt eine Aktion in Alltagssprache aus. Ein Plan-Cache-Replay eines bereits bekannten Schritts kostet nichts. Ein Schritt, den die Sicherheitsgatter zurückhalten, kommt als Inhalt mit Begründung zurück, nicht als Fehler.
`browser_extract`	ein Modellaufruf	Zieht strukturierte Daten aus der Seite, optional gegen ein JSON-Schema; deutsche Zahlen- und Datumsformate bleiben genau so, wie die Seite sie schreibt.
`browser_run_task`	mehrere Modellaufrufe	Übergibt ein mehrseitiges Ziel an den gehosteten Agenten und wartet bis zu `waitSeconds` (Standard 45). Nimmt eine `startUrl` — eine Session ohne offene Seite und ohne Start-URL wird abgelehnt, damit der Agent nie auf einem leeren Tab beginnt, und eine Aufgabe mit Start-URL bleibt auf dieser Seite, solange `pinToStartSite` nicht auf false gesetzt ist. Läuft die Aufgabe dann noch, kommt eine `taskId` zurück; der Ausgang ist `completed`, `terminated` oder `failed`.
`browser_task_status`	kein Modellaufruf	Fragt eine Aufgabe per ID ab — optional mit Wartezeit — und liefert Antwort, Daten und das Urteil des Prüfers, sobald sie fertig ist. Braucht keinen Browser.
`browser_new_session`	kein Modellaufruf	Öffnet eine weitere Session: eine zweite Seite parallel, ein gespeichertes Profil, Tresor-Zugangsdaten per ID, einen reservierten Pool oder eine andere Locale und Zeitzone.
`browser_list_sessions`	kein Modellaufruf	Listet die Sessions dieser Verbindung und die übrigen offenen Sessions der Organisation, die nach einem Reconnect per ID angebunden werden können.
`browser_close_session`	kein Modellaufruf	Gibt eine Session frei. Lehnt ab — und sagt es —, solange eine von dieser Verbindung gestartete Aufgabe noch darauf läuft.
`browser_session_info`	kein Modellaufruf	Meldet ID, Ablauf und CDP-Endpunkt einer Session. Es erzeugt nie eine und ist darum jederzeit gefahrlos aufrufbar.
`browser_watch_url`	kein Modellaufruf	Liefert einen Dashboard-Link, den eine Person öffnet, um die Session live zu sehen und als Owner zu übernehmen — für einen Einmalcode, eine Consent-Wand oder einen Login, den der Tresor nicht schafft.

Workflows, Trigger, Tresor und Audit

Die Verwaltungsoberfläche, nur dort gelistet, wo das Deployment sie hat. Keines dieser Tools kostet einen Modellaufruf; ein Workflow-Lauf kostet, was seine Blöcke kosten.

Name	Typ	Beschreibung
`workflow_list · workflow_get · workflow_publish`	kein Modellaufruf	Aufgezeichnete, versionierte Jobs. Beim Veröffentlichen wird die ganze Definition auf einmal geprüft und jedes Problem zurückgegeben; Versionen sind unveränderlich, und ein Lauf führt die Version aus, mit der er gestartet ist.
`workflow_run · workflow_run_status · workflow_cancel_run`	die Kosten der Blöcke	Führt einen Workflow in einer Session aus, mit derselben begrenzten Wartezeit wie eine Aufgabe, fragt einen Lauf per ID ab oder bittet ihn, zwischen zwei Blöcken anzuhalten.
`workflow_heal_list · workflow_heal_decide`	kein Modellaufruf	Reparaturvorschläge, geschrieben nachdem ein Selektor nicht mehr traf. Annehmen veröffentlicht eine neue Version; nichts ändert sich, bis eine Person entscheidet.
`trigger_create · trigger_list · trigger_set_status · trigger_firings`	kein Modellaufruf	Plant einen Workflow mit Cron-Ausdruck und IANA-Zeitzone, pausiert und reaktiviert ihn und beantwortet, warum ein Trigger ausgelöst hat oder nicht. Webhook-Trigger werden im Dashboard angelegt, weil ihr Signaturgeheimnis einmal gezeigt wird und nicht durch eine Unterhaltung wandern darf.
`credential_list · profile_list`	kein Modellaufruf	Tresor-Zugangsdaten nach Name und Feldnamen — nie ein Wert — und gespeicherte Browser-Profile, beide beim Öffnen einer Session per ID referenziert. Kein Tool erzeugt Zugangsdaten oder liest sie zurück.
`audit_log`	kein Modellaufruf	Das manipulationssichere Protokoll dessen, was tatsächlich getan wurde, standardmäßig auf die aktuelle Session gefiltert. Der prüfbare Export für einen Auditor bleibt `GET /v1/audit/export`.

Drei Ausgänge, und das Handle

browser_run_task endet in einem von drei Zuständen, und sie sind nicht dasselbe. completed heißt: Die Arbeit ist erledigt, und ein separater Prüfer hat sie gegen die neu gelesene Seite bestätigt. terminated heißt: Der Agent hat nachgesehen, und die Seite bietet das schlicht nicht — die richtige Antwort ist, dem Nutzer zu sagen, was der Prüfer gesehen hat, nicht ein neuer Versuch. failed heißt: Etwas ist kaputtgegangen, und ein Wiederholungsversuch ist vernünftig.

Eine Aufgabe ist per Vertrag asynchron. Das Tool wartet eine begrenzte Zeit und liefert das fertige Ergebnis, wenn es kann; eine danach noch laufende Aufgabe gibt eine taskId zurück und läuft im Hintergrund weiter, abzufragen mit browser_task_status. Ein Agent, der die Aufgabe erneut startet, weil der erste Aufruf „zu früh zurückkam“, tut genau das, wovor die Tool-Beschreibung am deutlichsten warnt. Wartende Tools senden MCP-Fortschrittsmeldungen, damit ein Client, der sie angefordert hat, sein eigenes Timeout nicht auslösen lässt.

Was nie durch die Unterhaltung wandert

Kein Tool erzeugt Zugangsdaten oder liest sie zurück. Logins nutzen den Tresor per Referenz: credential_list zeigt Namen und Feldnamen, die ID wandert in browser_new_session oder in einen Workflow-Login-Block, und das Geheimnis wird im Browser getippt, gegen die Seite geprüft und nie zurückgegeben. Webhook-Signaturgeheimnisse werden genauso behandelt — von einer Person im Dashboard angelegt, einmal gezeigt —, weshalb trigger_create nur Zeitpläne annimmt.

Wenn eine Person gebraucht wird — ein Einmalcode, eine unerwartete Consent-Wand, ein Login, den der Tresor nicht schafft — liefert browser_watch_url einen Dashboard-Link. Die Person sieht die Session live und kann als Owner der Organisation Maus und Tastatur übernehmen; der Agent wartet, bis sie sagt, dass sie fertig ist.

Fehler, Self-Hosting und der Skill

Geht ein Tool-Aufruf schief — ein zurückgehaltener destruktiver Klick, eine abgelaufene Session, eine verweigerte Extraktion — kommt der Fehlschlag als Ergebnis des Tools zurück, nicht als MCP-Protokollfehler. Der Agent kann die Meldung lesen und reagieren, statt dass die ganze Unterhaltung an einem Transportfehler stirbt.

Für die lokale Form ist BROWSERBERG_API_KEY Pflicht, und BROWSERBERG_BASE_URL richtet den Server auf ein selbst gehostetes Deployment. Das Paket braucht einen Server mit Wire-Protokoll 1.3.0 oder neuer und lehnt einen älteren beim Start mit einer Meldung ab, die sagt, welche Seite zu aktualisieren ist. Der gehostete Endpunkt nimmt einen API-Schlüssel oder ein OAuth-Token vom eigenen Autorisierungsserver der Control Plane, etwa für claude.ai – siehe claude.ai verbinden.

Das npm-Paket liefert einen Skill mit — skills/browserberg/ —, der einem Agenten beibringt, wann er eine Seite selbst liest, wann er eine Aufgabe delegiert, wann er einen Workflow aufzeichnet, wie er die drei Ausgänge liest und was er nie tippt. Installiere ihn neben dem Server; er macht aus der Tool-Liste gutes Verhalten. Wie sich die MCP-Integration vom direkten Ansprechen der API unterscheidet, zeigt die MCP-Integrationsseite.

Tiefer einsteigen

Schnellstart Dieselbe Session, gesteuert aus deinem eigenen Code
Beobachten, handeln, extrahieren Was die Browser-Tools darunter tun
Aufgaben-Referenz Die Agentenschleife hinter browser_run_task