Bring your own AI

Justflows does not sell AI, host models, or bill for tokens. You bring your own, in one of two ways:

Connect an AI agent (MCP)#

1. 1

   Turn it on

   Admin → Settings → API. Turn on the management API, then Let AI agents connect over MCP. Both switches apply immediately.

2. 2

   Copy the server URL

   The MCP server URL is https://your-site.example/api/mcp. It comes from APP_URL, or from the request when APP_URL is a loopback address.

3. 3

   Pick your app

   Under Connect an AI agent, choose your client. Key-based clients get a Create a key for … button and copy-ready setup.

Key presets

A key can never exceed its creator's capabilities, and on every request it is re-checked against the owner's current access. Settings → API → Connected apps lists every OAuth grant with when it was created and last used; Revoke ends it immediately.

Client setup#

Replace URL with your MCP server URL and KEY with a jfk_… key.

{ "mcpServers": { "justflows": { "url": "URL", "headers": { "Authorization": "Bearer KEY" } } } }

claude mcp add --transport http justflows URL --header "Authorization: Bearer KEY"

{ "servers": { "justflows": { "type": "http", "url": "URL", "headers": { "Authorization": "Bearer KEY" } } } }

{ "mcpServers": { "justflows": { "command": "npx", "args": ["-y", "mcp-remote", "URL", "--header", "Authorization: Bearer KEY"] } } }

• claude.ai and Claude Desktop: Settings → Connectors → Add custom connector, paste the URL, and sign in to Justflows to approve.
• ChatGPT: Settings → Apps & Connectors → Advanced settings, turn on developer mode, then create a connector with the URL and choose OAuth.

What agents can do#

Tools are generated from the Management API. A tool call runs the same handler in-process, with the same capability and scope checks. A session sees only the tools it can use, and calling an unlisted tool is refused. Start with site_describe.

• Validated blocks. content_create and content_update check block bodies against the live block registry before anything is written. Unknown types, missing required props, and invalid options come back as errors the model can fix.
• Drafts by default. New entries are drafts unless publish: true is passed and the session holds content:publish. Updates need expectedVersion, so an agent never silently overwrites a newer edit.
• Safe uploads. media_upload downloads public http(s) URLs only, with the SSRF guard on every redirect. Uploads are limited to 20 MB and the library's allowed types.
• Audited and attributed. Every change is written to the audit log as ai.tool_called (never the arguments), and revision history shows "… · via Claude" with the client name.

The server also offers resources (justflows://docs/authoring, justflows://docs/blocks, and one per content type) and prompts: draft_post, translate_entry, seo_metadata, and audit_alt_text.

The admin assistant (BYOK)#

Admin → Settings → AI stores site-wide provider keys and turns the assistant on.

Keys are encrypted at rest and write-only: the admin shows the provider and the last four characters, and no response ever contains a key. Test connection loads the key's models for the model picker. Every provider call is made by the server. Users with ai:use can also add a personal key through the API; it takes precedence over the site key for the same provider.

Using it

• Assistant in the sidebar opens a chat panel that streams answers and uses the same tools as the MCP server, as you. It can never do more than you can.
• Read-only tools run automatically. Every create, update, delete, publish, or settings change appears as a card with a before/after preview and runs only when you click Approve. The server enforces this, not the browser.
• The content editor's AI ✦ menu rewrites, shortens, or expands selected text; writes the excerpt and SEO title and description; writes image alt text (vision models); drafts from a brief; and translates into a linked draft. Nothing is saved until you apply it and save.
• The panel shows token usage and the optional daily limit. Provider errors (invalid key, quota, unavailable model, rate limit) are reported in plain words.
• Conversations stay in your browser tab. They are not stored on the server. Only what you and the tools put into a conversation is sent to the provider.

Settings and capabilities#

The ai:use capability lets a user use the assistant and add personal keys. Administrators and editors have it by default; grant it to any role or user like other capabilities. Configuring providers and the switches needs settings:manage. Migration 0036_ai_byok adds the provider, usage, and OAuth tables on PostgreSQL, MySQL, and MariaDB.

Security model#

• Prompt injection is assumed. Post bodies, comments, profiles, and media metadata are treated as data, not instructions, and no tool output can trigger a write without your click.
• Live permissions. Every call re-checks the user's current role, access policy, and content, locale, and ownership scope. Revoking a user, key, or grant cuts off access on the next request.
• OAuth hardening. PKCE S256 only, exact redirect URIs, single-use five-minute codes, one-hour access tokens, rotating refresh tokens (reuse revokes the grant), and tokens bound to their resource. Codes, tokens, and client secrets are stored only as SHA-256 hashes.
• Rate limits per key or grant and per IP, with stricter limits on the OAuth endpoints. Media upload, static export, cache, and activation keep their own limits when called as tools.
• Secrets never appear in logs, audit entries, tool results, errors, or the schema.

Add tools from a plugin#

Append McpToolDefinition objects through the mcp.tools filter. The host lists the tool only to sessions that hold capability, checks it again on every call, audits changes, and attributes revisions. Your handler does any per-resource checks. Names are snake_case, prefixed with your plugin, and must not shadow a core tool.

ctx.hooks.filter("mcp.tools", (tools) => [
  ...tools,
  {
    name: "acme_seo_score",
    description: "Score an entry for SEO and list what to fix.",
    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
    capability: "content:read",
    annotations: { readOnlyHint: true },
    handler: async ({ id }, { siteId }) => scoreEntry(siteId, String(id)),
  },
]);