Connecting an agent

Goal: spin up a Claude / ChatGPT / custom agent that can read and write ScaiCMS content.

1. Decide what the agent should be able to do#

• Read-only research bot — docs:read is enough.
• Drafting bot — needs docs.write on a chosen namespace, no manage.
• Full dev-team bot — needs docs.read, docs.write, docs.manage on one or more namespaces.

2. Issue an API key#

In the admin UI: API keys → + New.

• Name: descriptive (e.g. claude-docs-bot).
• Bind to: a Group if multiple humans/agents share it, a User if it's for one human's automations.
• Scopes: comma-separated. Examples:
  • docs:read — broad read.
  • docs:write:scaigrid — write only to scaigrid.
  • docs:read, docs:write:scaicms, docs:manage:scaicms — full control of one namespace.

Copy the plaintext from the one-time modal before closing it.

3a. Connect via MCP#

1
2
3

export SCAICMS_API_KEY=scai_live_…
export SCAICMS_SITE_ID=30847722-…
python -m scaicms.mcp.server

Configure your agent to use the resulting stdio MCP server. It will see all manage_* tools, including manage_documentation for docs writes.

3b. Connect via REST + Python SDK#

1
2
3
4
5
6
7
8
9

from scaicms_docs import DocsClient

with DocsClient(base_url="https://yourdomain", api_key="scai_live_…") as c:
    page = c.pages.upsert(
        "scaicms", "v1", "concepts/something",
        title="Something",
        body_md="# Something\n\nDrafted by my agent.",
        frontmatter={"author": "claude-bot"},
    )

4. Verify access matches the scope#

Try writing into a namespace the key shouldn't reach:

1
2
3
4

curl -X PUT -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"nope","body_md":"x"}' \
  "$API/api/v1/docs/some-other-namespace/v1/intro"

You should get 403 SCOPE_DENIED. Good — that means the scope is holding.

What's next#

• Drop docs/agent-bundle/ into the agent's system prompt for full read/write coverage in plain English.
• Use scaicms-docs CLI for one-off scripts.