MCP-Server

Dies ist die Protokollreferenz. Wenn Sie Claude oder ChatGPT einfach auf Ihre Engine richten und mit ihr sprechen möchten, ist Ihren Agenten verbinden die richtige Seite — sie behandelt die Client-Seite. Diese hier erklärt, was darunter passiert.

Der Endpunkt

POST https://your-host/mcp

Eine URL, auf demselben Origin wie das Dashboard und die REST API. Der Transport ist streamable HTTP mit JSON-RPC 2.0 über POST; es gibt keinen separaten SSE-Endpunkt zum Konfigurieren.

Protokollversion	2025-06-18
Servername	fastsite
Fähigkeiten	tools
Methoden	initialize, ping, tools/list, tools/call

Alles andere gibt -32601 zurück. Benachrichtigungen antworten mit 202 ohne Inhalt. Batches werden bis zu 20 Nachrichten akzeptiert.

Authentifizierung

OAuth 2.1, öffentlicher Client, PKCE erforderlich. Ein Client, der Ihre Engine noch nie gesehen hat, kann den gesamten Ablauf selbständig entdecken und abschließen — nichts wird vorab manuell registriert.

1. Der Client sendet POST an /mcp ohne Token und erhält 401 sowie einen WWW-Authenticate-Header, der die Ressourcen-Metadaten-URL benennt.
2. Er ruft /.well-known/oauth-protected-resource ab, das auf den Autorisierungsserver verweist.
3. Er ruft /.well-known/oauth-authorization-server für die Endpunkte und die unterstützten Scopes ab.
4. Er registriert sich unter POST /oauth/register und erhält eine client_id. Es wird kein Secret ausgegeben.
5. Er öffnet /oauth/authorize in einem Browser. Sie melden sich mit Ihrem normalen Engine-Konto an und genehmigen die angeforderten Scopes.
6. Er tauscht den Code unter /oauth/token gegen ein Access Token und ein Refresh Token aus.
7. Er ruft /mcp mit Authorization: Bearer … auf.

Autorisierungscode	60 Sekunden, einmalig verwendbar
Access Token	1 Stunde
Refresh Token	30 Tage, bei jeder Verwendung rotiert
PKCE	Nur S256 — plain wird abgelehnt

Refresh Tokens rotieren, und die Wiederverwendung eines bereits rotierten Tokens wird als Diebstahl gewertet: Die gesamte Token-Familie wird widerrufen und der Client muss erneut autorisieren. Codes und Tokens werden gehasht gespeichert, niemals im Klartext.

Was ein Token erreichen kann

Scopes entscheiden welche Art von Operation erlaubt ist. Ihr Konto entscheidet, auf welche Sites es sich anwenden lässt.

Ein Token enthält die von Ihnen genehmigten Scopes. Jedes site-bezogene Tool prüft dann den eigenen Zugriff des angemeldeten Benutzers auf diese Site — direkte Mitgliedschaft, Mitgliedschaft im Team der Site oder die Admin-Rolle. Ein Agent, der mit Ihrem Konto verbunden ist, kann die Sites erreichen, die Sie erreichen können, und nichts darüber hinaus. Das Gewähren von content:write erweitert das nicht; es entscheidet nur, was der Agent auf Sites tun darf, zu denen Sie bereits Zugang haben.

Das Scope-Vokabular wird mit API-Schlüsseln geteilt, sodass ein Tool und ein Endpunkt dasselbe durchsetzen. Die vollständige Liste befindet sich auf der REST API-Seite.

Tools

Mehr als fünfzig, die alles abdecken, was das Dashboard macht. tools/list ist der maßgebliche Katalog für Ihre Version — so sieht er aus.

Die Wiederherstellung der Engine fehlt bewusst. Disaster Recovery ist ein Befehl, den Sie auf dem Server mit gestoppten Workern ausführen, nicht etwas, das ein Agent auslösen kann.

Mit dem Leitfaden beginnen

get_authoring_guide ist das Tool, das zuerst aufgerufen werden sollte, bevor Sie eine Shell gestalten oder einen Inhalt schreiben. Übergeben Sie ein Site-Handle und es bezieht die Spracheinstellungen und die Embed-Syntax der Site ein.

{
  "method": "tools/call",
  "params": {
    "name": "get_authoring_guide",
    "arguments": { "site": "blog" }
  }
}

Es gibt die Regeln zurück, die das Build-Audit tatsächlich durchsetzt: nur Body-HTML, erforderliche Bildabmessungen und Alt-Text, die Zero-JavaScript-Beschränkung sowie die Embed-Syntax für Medien und Komponenten. Ein Agent, der es zuerst liest, schreibt Markup, das veröffentlicht wird; einer, der rät, schreibt Markup, das abgelehnt wird.

Inhalte erstellen

{
  "method": "tools/call",
  "params": {
    "name": "create_post",
    "arguments": {
      "site": "blog",
      "title": "Hello, world",
      "body_html": "<p>Shipped by an agent.</p>",
      "status": "published"
    }
  }
}

Bilder werden per Medien-ID referenziert, nie über eine externe URL — upload_media_from_url importiert eines und gibt den Embed-Snippet zurück, der in den Body eingefügt werden kann. Alt-Text ist Pflicht.

Wenn ein Client keine Verbindung herstellt

• Discovery gibt localhost zurück. Die Engine gibt ihre eigene URL in den OAuth-Metadaten bekannt. Wenn APP_URL noch auf dem Standardwert ist, wird einem Remote-Client mitgeteilt, gegen localhost zu autorisieren, und die Registrierung schlägt fehl. Setzen Sie APP_URL auf die tatsächliche öffentliche URL.
• Der Endpunkt muss erreichbar und HTTPS sein. Remote-Clients führen keinen OAuth-Flow über einfaches HTTP zu einem Nicht-Loopback-Host durch.
• Überprüfen Sie zuerst die 401. Ein korrektes nicht authentifiziertes POST /mcp gibt 401 mit einem WWW-Authenticate-Header zurück. Wenn es etwas anderes zurückgibt, liegt das Problem vor der Engine, nicht im Client.
• Stdio-only-Clients benötigen eine Bridge. Verweisen Sie diese auf npx mcp-remote https://your-host/mcp.

Bevorzugen Sie einfache HTTP-Aufrufe? Die REST API deckt dieselben Operationen mit einem API-Schlüssel anstelle eines Tokens ab.