fastsite MCP server — protokol, OAuth og værktøjsreference

Dette er protokolreferencen. Hvis du blot vil pege Claude eller ChatGPT mod din motor og begynde at tale med den, er tilslutning af din agent den side, du ønsker — den dækker klientsiden. Denne side dækker, hvad der sker underneden.

Endepunktet

POST https://your-host/mcp

Én URL, på samme oprindelse som dashboardet og REST API'et. Transport er streambar HTTP med JSON-RPC 2.0 over POST; der er intet separat SSE-endepunkt at konfigurere.

Protokolversion	`2025-06-18`
Servernavn	`fastsite`
Funktioner	`tools`
Metoder	`initialize`, `ping`, `tools/list`, `tools/call`

Alt andet returnerer -32601. Notifikationer svarer med 202 uden brødtekst. Batches accepteres op til 20 beskeder.

Værktøjsfejl er resultater, ikke protokolfejl

Når et værktøj fejler — et manglende site, en afvist shell-fil, en valideringsfejl — får du et normalt resultat med isError: true og en læsbar besked, ikke en JSON-RPC-fejl. Det er bevidst: en model kan læse beskeden og korrigere sig selv, hvilket den ikke kan gøre ved en fejl på transportniveau.

Autentificering

OAuth 2.1, offentlig klient, PKCE påkrævet. En klient, der aldrig har set din motor før, kan på egen hånd opdage og gennemføre hele flowet — intet er forudregistreret manuelt.

Klienten sender POST til /mcp uden token og modtager 401 samt en WWW-Authenticate-header, der angiver ressourcemetadata-URL'en.
Den henter /.well-known/oauth-protected-resource, som peger på autorisationsserveren.
Den henter /.well-known/oauth-authorization-server for endepunkterne og de understøttede scopes.
Den registrerer sig selv via POST /oauth/register og modtager et client_id. Der udstedes ingen hemmelighed.
Den åbner /oauth/authorize i en browser. Du logger ind med din normale motorkonto og godkender de ønskede scopes.
Den veksler koden ved /oauth/token for et adgangstoken og et opdateringstoken.
Den kalder /mcp med Authorization: Bearer ….

Autorisationskode	60 sekunder, engangsbrug
Adgangstoken	1 time
Opdateringstoken	30 dage, roteres ved hvert brug
PKCE	Kun `S256` — `plain` afvises

Opdateringstokens roteres, og genbrug af et allerede roteret token behandles som tyveri: hele tokenfamilien tilbagekaldes, og klienten skal autorisere igen. Koder og tokens gemmes hashede, aldrig i klartekst.

Klienter skal anmode om scopes eksplicit

Der er intet standard-scope-sæt. En autorisationsanmodning, der helt udelader scope, afvises med invalid_scope frem for at blive tildelt et sikkert minimum. Hvis du skriver en klient, skal du anmode om præcis det, du har brug for — samtykkeskærmen viser brugeren en letlæselig beskrivelse af hvert enkelt scope.

Hvad et token kan tilgå

Scopes afgør hvilken slags handling der er tilladt. Din konto afgør hvilke sites det gælder for.

Et token bærer de scopes, du har godkendt. Hvert site-afgrænset værktøj kontrollerer derefter den indloggede brugers egen adgang til det pågældende site — direkte medlemskab, medlemskab af sitets team eller administratorrollen. En agent tilknyttet din konto kan tilgå de sites, du selv kan tilgå, og intet andet. At tildele content:write udvider ikke dette; det afgør kun, hvad agenten må gøre på sites, du allerede har adgang til.

Scope-vokabularet er delt med API-nøgler, så et værktøj og et endepunkt håndhæver det samme. Den fulde liste findes på REST API-siden.

Værktøjer

Mere end halvtreds, der dækker alt, hvad dashboardet kan. tools/list er den autoritative katalog for din version — dette er formen på det.

Indhold

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

Medier

list_media, upload_media_from_url, delete_media, restore_media, purge_media

Shell 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

Publicering

publish_site, preview_site, get_build_status, list_jobs

Sites og routing

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

Webhooks og sikkerhedskopier

list_webhooks, create_webhook, webhook_deliveries, backup_site, list_backups, restore_backup

Teams og legitimationsoplysninger

list_teams, create_team, invite_member, accept_invite, og GitHub-legitimationsværktøjerne, der bruges til publicering

Gendannelse af selve motoren er bevidst fraværende. Disaster recovery er en kommando, du kører på maskinen med arbejderne stoppet, ikke noget en agent kan udløse.

Start med guiden

get_authoring_guide er det værktøj, du skal kalde først, inden du designer en shell eller skriver en brødtekst. Angiv et site-handle, og det foldes ud med det pågældende sites sprog og embed-syntaks.

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

Det returnerer de regler, som build-revisionen faktisk håndhæver: kun brødtekst-HTML, påkrævede billedmål og alt-tekst, nul-JavaScript-kravet samt embed-syntaksen for medier og komponenter. En agent, der læser det først, skriver markup, der publiceres; en der gætter, skriver markup, der afvises.

Oprettelse af indhold

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

Billeder refereres via medie-id, aldrig via ekstern URL — upload_media_from_url importerer et billede og returnerer det embed-uddrag, der skal indsættes i brødteksten. Alt-tekst er påkrævet.

Hvis en klient ikke vil oprette forbindelse

Discovery returnerer localhost. Motoren annoncerer sin egen URL i OAuth-metadataene. Hvis APP_URL stadig er standardværdien, får en fjernklient besked om at autorisere mod localhost og fejler ved registrering. Sæt APP_URL til den reelle offentlige URL.
Endepunktet skal være tilgængeligt og bruge HTTPS. Fjernklienter vil ikke gennemføre et OAuth-flow over almindelig HTTP til en ikke-loopback-host.
Tjek 401 først. En korrekt uautoriseret POST /mcp returnerer 401 med en WWW-Authenticate-header. Hvis den returnerer noget andet, er problemet foran motoren, ikke i klienten.
Stdio-kun-klienter har brug for en bro. Peg dem mod npx mcp-remote https://your-host/mcp.

Foretrækker du almindelige HTTP-kald? REST API'et dækker de samme handlinger med en API-nøgle i stedet for et token.