Skip to main content

🤖 Connecting an Assistant

MCP, the Model Context Protocol, lets an AI assistant read and draft Swift Axis stories through a set of tools, using an API token you create. This page will guide you through creating a token, choosing its scopes and setting up your client, so an assistant can work on the site on your behalf.

Summary

A token always acts as the owner who created it and is limited to the scopes you choose. Every tool that changes something runs as a dry run unless asked otherwise.

Before you start​

API tokens are for site owners. In the Studio, open "API & MCP". The page says "Let tools and AI assistants work with the site through API tokens. Each token acts as you, limited to the scopes you choose." If you are not an owner, it says API tokens are available to site owners only.

Creating a token​

  • Press "Create token" at the top of "API & MCP".
  • Give it a "Name", such as the tool that will use it. The placeholder suggests "Claude Desktop".
  • Tick the "Scopes" it needs. See below.
  • Choose when it "Expires": 30 days, 90 days, 1 year or never.
  • Press "Create token". A window headed "Copy your new token" shows it.
  • Copy it now. The token starts with sxa_ and is shown only once. If you lose it, revoke it and create another.

A token example looks like sxa_xxxxxxxx. Treat a real one like a password. Do not paste it into chats, documents or screenshots.

Choosing scopes​

Give a token the smallest set of scopes that does the job.

  • Read (read): read stories, topics, choices, tags, writers, Briefs and the rebuild status.
  • Write content (write:content): create and edit stories, topics, choices, ideas, tags, writers, Briefs, navigation and images. It cannot publish or delete.
  • Publish (publish): publish, schedule and unpublish content, and delete it.
  • Settings (settings): site settings and analytics, rebuilds, export and import, contact messages, readers and editors.
  • Manage pages (admin:pages): owners only. List, create, edit, publish, unpublish and delete site pages such as About.

For a drafting assistant, read and write:content is usually enough. See Good practice.

Setting up the client​

On the same page, "Connect an MCP client" shows your site's endpoint, labelled "Endpoint (Streamable HTTP)", with a "Copy" button. It is your site's address followed by /mcp. Below it are ready-made configurations for:

  • Claude Desktop / Cursor (mcpServers): a configuration block that lists a server named "swift-axis-news" with its address and an Authorization header.
  • Claude Code: a command that adds the server over HTTP with the header.
  • curl: a command to list the tools, useful for checking that the token works.

Replace the placeholder with your token. A Claude Desktop or Cursor entry looks like this, with a placeholder token:

{
  "mcpServers": {
    "swift-axis-news": {
      "url": "https://your-site.example/mcp",
      "headers": { "Authorization": "Bearer sxa_xxxxxxxx" }
    }
  }
}

Every request needs the bearer token. A missing, expired or revoked token is refused with a 401 error.

Keeping an eye on tokens​

The "Tokens" table lists each token's name, the first characters of the token, its scopes, when it was created and expires, when it was last used and its status ("Active", "Expired" or "Revoked"). Press "Revoke" on an active token and confirm to cut off access immediately.

The "Recent activity" table lists changes made with tokens, newest first, kept for 90 days. Reads are not logged.

warning

A token stops working if the owner who created it stops being an owner, and it works again if they are made an owner again, unless it was revoked.

Where next​

Tool Reference

What each tool does and which scope it needs.

Good Practice

Dry runs, publishing, images and the audit log.