fastsite MCP server — protokoll, OAuth och verktygsreferens

Detta är protokollreferensen. Om du bara vill peka Claude eller ChatGPT mot din motor och börja prata med den är ansluta din agent sidan du vill ha — den täcker klientsidan. Den här täcker vad som händer under ytan.

Endpointen

POST https://your-host/mcp

En URL, på samma origin som instrumentpanelen och REST API:et. Transporten är streambar HTTP med JSON-RPC 2.0 över POST; det finns ingen separat SSE-endpoint att konfigurera.

Protokollversion	`2025-06-18`
Servernamn	`fastsite`
Funktioner	`tools`
Metoder	`initialize`, `ping`, `tools/list`, `tools/call`

Allt annat returnerar -32601. Notifikationer svarar med 202 utan body. Batchar accepteras upp till 20 meddelanden.

Verktygsfel är resultat, inte protokollfel

När ett verktyg misslyckas — en saknad webbplats, en avvisad skalfil, ett valideringsfel — får du ett normalt resultat med isError: true och ett läsbart meddelande, inte ett JSON-RPC-fel. Det är avsiktligt: en modell kan läsa meddelandet och korrigera sig själv, vilket den inte kan göra med ett transportnivåfel.

Autentisering

OAuth 2.1, publik klient, PKCE krävs. En klient som aldrig har sett din motor tidigare kan identifiera och slutföra hela flödet på egen hand — ingenting är förregistrerat manuellt.

Klienten skickar POST till /mcp utan token och får 401 plus en WWW-Authenticate-header som namnger resursmetadatans URL.
Den hämtar /.well-known/oauth-protected-resource, som pekar på auktoriseringsservern.
Den hämtar /.well-known/oauth-authorization-server för endpoints och de stödda scopesen.
Den registrerar sig på POST /oauth/register och tar emot ett client_id. Ingen hemlighet utfärdas.
Den öppnar /oauth/authorize i en webbläsare. Du loggar in med ditt vanliga motorkonto och godkänner de begärda scopesen.
Den växlar koden vid /oauth/token mot en åtkomsttoken och en uppdateringstoken.
Den anropar /mcp med Authorization: Bearer ….

Auktoriseringskod	60 sekunder, engångsbruk
Åtkomsttoken	1 timme
Uppdateringstoken	30 dagar, roteras vid varje användning
PKCE	Endast `S256` — `plain` avvisas

Uppdateringstokens roteras, och återanvändning av en redan roterad token behandlas som stöld: hela tokenfamiljen återkallas och klienten måste auktorisera igen. Koder och tokens lagras hashade, aldrig i klartext.

Klienter måste begära scopes explicit

Det finns inget standardscope inställt. En auktoriseringsbegäran som utelämnar scope helt avvisas med invalid_scope snarare än att beviljas ett säkert minimum. Om du skriver en klient, be om exakt vad du behöver — samtycksskärmen visar användaren en beskrivning på vanlig text av vart och ett.

Vad en token kan nå

Scopes avgör vilken typ av operation som är tillåten. Ditt konto avgör vilka webbplatser det gäller.

En token bär de scopes du godkände. Varje webbplatsomfattat verktyg kontrollerar sedan den inloggade användarens egen åtkomst till den webbplatsen — direkt medlemskap, medlemskap i webbplatsens team, eller administratörsrollen. En agent ansluten till ditt konto kan nå de webbplatser du kan nå, och inget annat. Att bevilja content:write utvidgar inte det; det avgör bara vad agenten får göra på webbplatser du redan har tillgång till.

Scope-vokabulären delas med API-nycklar, så ett verktyg och en endpoint tillämpar samma sak. Den fullständiga listan finns på REST API-sidan.

Verktyg

Fler än femtio, som täcker allt som instrumentpanelen gör. tools/list är den auktoritativa katalogen för din version — detta är formen på det.

Innehåll

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

Skal och 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

Webbplatser och routing

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

Webhooks och säkerhetskopior

list_webhooks, create_webhook, webhook_deliveries, backup_site, list_backups, restore_backup

Team och inloggningsuppgifter

list_teams, create_team, invite_member, accept_invite, och GitHub-verktyg för inloggningsuppgifter som används vid publicering

Återställning av motorn är avsiktligt frånvarande. Katastrofåterställning är ett kommando du kör på maskinen med arbetarna stoppade, inte något en agent kan utlösa.

Börja med guiden

get_authoring_guide är verktyget att anropa först, innan du utformar ett skal eller skriver en body. Skicka ett webbplatshandtag så inkluderar det webbplatsens språkinställningar och inbäddningssyntax.

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

Det returnerar de regler som bygggranskaren faktiskt tillämpar: body-only HTML, obligatoriska bildmått och alt-text, noll-JavaScript-begränsningen och inbäddningssyntaxen för media och komponenter. En agent som läser det först skriver uppmärkning som publiceras; en som gissar skriver uppmärkning som avvisas.

Skapa innehåll

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

Bilder refereras med media-id, aldrig med extern URL — upload_media_from_url importerar en och returnerar inbäddningssnippeten att klistra in i bodyn. Alt-text är obligatorisk.

Om en klient inte vill ansluta

Identifieringen returnerar localhost. Motorn annonserar sin egen URL i OAuth-metadatan. Om APP_URL fortfarande är standard uppmanas en fjärrklient att auktorisera mot localhost och misslyckas med registreringen. Sätt APP_URL till den verkliga publika URL:en.
Endpointen måste vara nåbar och använda HTTPS. Fjärrklienter kör inte ett OAuth-flöde över vanlig HTTP till en icke-loopback-värd.
Kontrollera 401:an först. En korrekt oautentiserad POST /mcp returnerar 401 med en WWW-Authenticate-header. Om den returnerar något annat ligger problemet framför motorn, inte i klienten.
Stdio-only-klienter behöver en brygga. Peka dem mot npx mcp-remote https://your-host/mcp.

Föredrar du vanliga HTTP-anrop? REST API:et täcker samma operationer med en API-nyckel istället för en token.