fastsite MCP server — protokoll, OAuth og verktøyreferanse

Dette er protokollreferansen. Hvis du bare vil peke Claude eller ChatGPT mot motoren din og begynne å snakke med den, er tilkobling av agenten din siden du vil ha — den dekker klientsiden. Denne dekker hva som skjer under overflaten.

Endepunktet

POST https://your-host/mcp

Én URL, på samme opprinnelse som dashbordet og REST API-et. Transport er strømmbar HTTP med JSON-RPC 2.0 over POST; det er ingen separat SSE-endepunkt å konfigurere.

Protokollversjon	`2025-06-18`
Servernavn	`fastsite`
Funksjoner	`tools`
Metoder	`initialize`, `ping`, `tools/list`, `tools/call`

Alt annet returnerer -32601. Varsler svarer 202 uten innhold. Grupper aksepteres opp til 20 meldinger.

Verktøyfeil er resultater, ikke protokollfeil

Når et verktøy feiler — et manglende nettsted, en avvist skallfil, en valideringsfeil — får du et normalt resultat med isError: true og en menneskelig lesbar melding, ikke en JSON-RPC-feil. Det er bevisst: en modell kan lese meldingen og korrigere seg selv, noe den ikke kan gjøre med en feil på transportnivå.

Autentisering

OAuth 2.1, offentlig klient, PKCE påkrevd. En klient som aldri har sett motoren din før, kan oppdage og fullføre hele flyten på egen hånd — ingenting forhåndsregistreres manuelt.

Klienten sender POST til /mcp uten token og får 401 pluss en WWW-Authenticate-header som angir URL-en for ressursmetadata.
Den henter /.well-known/oauth-protected-resource, som peker på autorisasjonsserveren.
Den henter /.well-known/oauth-authorization-server for endepunkter og støttede omfang.
Den registrerer seg selv på POST /oauth/register og mottar en client_id. Ingen hemmelighet utstedes.
Den åpner /oauth/authorize i en nettleser. Du logger inn med den vanlige motorkontoen din og godkjenner de forespurte omfangene.
Den veksler inn koden på /oauth/token for et tilgangstoken og et oppdateringstoken.
Den kaller /mcp med Authorization: Bearer ….

Autorisasjonskode	60 sekunder, engangsbruk
Tilgangstoken	1 time
Oppdateringstoken	30 dager, roteres ved hver bruk
PKCE	Kun `S256` — `plain` avvises

Oppdateringstokener roteres, og gjenbruk av et allerede rotert token behandles som tyveri: hele tokenfamilien tilbakekalles og klienten må autorisere på nytt. Koder og tokener lagres hashed, aldri i klartekst.

Klienter må be om omfang eksplisitt

Det finnes inget standardomfang. En autorisasjonsforespørsel som utelater scope helt, avvises med invalid_scope i stedet for å bli tildelt et trygt minimum. Hvis du skriver en klient, be om nøyaktig det du trenger — samtykkeskjermen viser brukeren en lettfattelig beskrivelse av hvert enkelt omfang.

Hva et token kan nå

Omfang avgjør hvilken type operasjon som er tillatt. Kontoen din avgjør hvilke nettsteder det gjelder for.

Et token bærer omfangene du godkjente. Hvert nettstedsomfattende verktøy sjekker deretter den innloggede brukerens egen tilgang til det nettstedet — direkte medlemskap, medlemskap i nettstedets team, eller administratorrollen. En agent koblet til kontoen din kan nå nettstedene du kan nå, og ingenting annet. Å gi content:write utvider ikke det; det avgjør bare hva agenten kan gjøre på nettsteder du allerede har tilgang til.

Omfangsvokabularet deles med API-nøkler, slik at et verktøy og et endepunkt håndhever det samme. Den fullstendige listen finnes på REST API-siden.

Verktøy

Mer enn femti, som dekker alt dashbordet gjør. tools/list er den autoritative katalogen for din versjon — dette er formen på den.

Innhold

list_posts, get_post, create_post, create_page, update_post, delete_content, restore_content, purge_content, list_trash, fact_check

Media

list_media, upload_media_from_url, delete_media, restore_media, purge_media

Skall og design

shell_list_files, shell_get_file, shell_put_file, shell_snapshot, shell_restore, list_components, upsert_component, delete_component

Lokalisering

add_language, remove_language, translate_site

Publisering

publish_site, preview_site, get_build_status, list_jobs

Nettsteder og ruting

list_sites, create_site, update_site, list_redirects, upsert_redirect, delete_redirect, list_scripts, upsert_script, delete_script

Webhooks og sikkerhetskopier

list_webhooks, create_webhook, webhook_deliveries, backup_site, list_backups, restore_backup

Team og legitimasjon

list_teams, create_team, invite_member, accept_invite, og GitHub-legitimasjonsverktøyene som brukes til publisering

Gjenoppretting av selve motoren er bevisst fraværende. Katastrofegjenoppretting er en kommando du kjører på maskinen med arbeiderne stoppet, ikke noe en agent kan utløse.

Start med veiledningen

get_authoring_guide er verktøyet du bør kalle først, før du utformer et skall eller skriver innhold. Angi et nettstedshåndtak og det inkluderer nettstedets lokaliteter og innbyggingssyntaks.

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

Det returnerer reglene byggerevisjonen faktisk håndhever: kun innholds-HTML, påkrevde bildedimensjoner og alt-tekst, null-JavaScript-begrensningen, og innbyggingssyntaksen for media og komponenter. En agent som leser det først, skriver markup som publiseres; en som gjetter, skriver markup som avvises.

Opprette innhold

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

Bilder refereres til med media-id, aldri med ekstern URL — upload_media_from_url importerer ett og returnerer innbyggingssnutten som skal limes inn i innholdet. Alt-tekst er påkrevd.

Hvis en klient ikke vil koble til

Oppdagelse returnerer localhost. Motoren annonserer sin egen URL i OAuth-metadataene. Hvis APP_URL fortsatt er standard, blir en ekstern klient bedt om å autorisere mot localhost og mislykkes ved registrering. Sett APP_URL til den virkelige offentlige URL-en.
Endepunktet må være tilgjengelig og bruke HTTPS. Eksterne klienter vil ikke kjøre en OAuth-flyt over vanlig HTTP til en ikke-loopback-vert.
Sjekk 401 først. En korrekt uautentisert POST /mcp returnerer 401 med en WWW-Authenticate-header. Hvis den returnerer noe annet, er problemet foran motoren, ikke i klienten.
Stdio-bare klienter trenger en bro. Pek dem mot npx mcp-remote https://your-host/mcp.

Foretrekker du vanlige HTTP-kall? REST API-et dekker de samme operasjonene med en API-nøkkel i stedet for et token.