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. On a multisite installation each site shows its own /api/mcp, and a key or sign-in for one site is refused on another.

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. A key with site:admin also holds every capability plugins register, including plugins installed later, as long as its owner still has them; core capabilities are never widened this way. The same jfk_ key works on plugin routes, except keys limited to content types, locales, sites, or ownership, because plugin routes do not check those scopes.

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.
• Agents stay on their site. A key, grant, or agent session acts only on the site it belongs to. The host refuses workspace operations and limit changes whenever an agent, API key, or connected app is behind the call, whatever a plugin's code does.
• Secrets are filtered out. Tool results, including plugin tools, have credential fields, environment-file text, private keys, and authorization values redacted before they reach an agent or a provider.

Add tools from a plugin#

Agents can use a plugin only where its author allows it. Add the mcp option to a ctx.http route and the route becomes one MCP tool that runs the route's own handler, so validation, capability checks, and side effects stay in one place.

ctx.http.put("products/:id", saveProduct, {
  mcp: {
    name: "acme_products_save",
    description: "Save a product's price and stock. Read it first with acme_products_get.",
    capability: "products:update",
    inputSchema: { type: "object", properties: { price: { type: "string" }, stock: { type: "integer" } } },
  },
});

• Path parameters such as :id become required string arguments. Other arguments are the query string for GET and DELETE, and the JSON body otherwise.
• The handler gets req.session with role: "api-key" (the owner's role for the admin assistant) and the capabilities the agent may use right now. Keep checking them as for any caller.
• The tool is listed only where the plugin is active and only to sessions holding capability. GET tools are read-only; other tools are audited. Set annotations such as destructiveHint to say more.
• The route's rateLimit applies per agent. Upload routes cannot be tools, and a file response is not passed to the agent.
• The mcp.tools filter no longer lists or runs tools. Offer a route with the mcp option instead.