AI Integration

QUIQQER can expose selected system functionality to AI clients and agents. The recommended integration path is MCP, backed by OAuth or API-token authentication and explicit QUIQQER permissions.

This section explains the architecture, account model, permissions, MCP tools, skills, and security rules for connecting AI clients to a QUIQQER installation.

Integration Model

A typical setup has four parts:

Part	Purpose
AI client	The external tool or agent, for example a desktop AI client, coding agent, or automation runner.
Authentication	An interactive OAuth authorization or a manually created API token.
QUIQQER user	The account used by the AI client. Its groups and permissions define what the AI can do.
MCP server	The quiqqer/ai-mcp package endpoint that exposes tools and resources to the AI client.

Interactive OAuth clients act as the user who approves the connection. Unattended integrations should use separate QUIQQER accounts and tokens. Do not use administrator or superuser accounts for normal MCP workflows.

What MCP Provides

MCP is a protocol for exposing tools and resources to AI clients. In QUIQQER, MCP tools are provided by installed packages.

Current examples:

• quiqqer/ai-mcp provides the MCP server, authentication integration, session resources, skill resources, and basic server information.
• quiqqer/core provides core MCP tools for projects, sites, media, and cache handling.
• quiqqer/bricks provides MCP tools for brick types, bricks, and site brick area assignments.
• Other packages can add MCP tools through package providers.
• Packages can also provide MCP skills, which are reusable Markdown instructions for AI clients.

Tools are only available when the authenticated QUIQQER user has the required permissions. Grant the smallest set of permissions needed for the AI workflow.

Recommended First Setup

For an interactive client such as Codex:

1. Install quiqqer/ai-mcp.
2. Make sure dynamic client registration is enabled in the OAuth settings.
3. Grant a QUIQQER user only the required MCP and normal project permissions.
4. Add the /mcp URL to the client.
5. Complete the QUIQQER login and consent flow in the browser.
6. Test read-only tools before enabling write tools.

For unattended automation, create a restricted AI account:

1. Create a dedicated QUIQQER user, for example ai-content-editor.
2. Put the user into a dedicated group for AI access.
3. Create an API token for that user.
4. Grant only the required MCP permissions and normal QUIQQER project permissions.
5. Store the token in a secret store and test read-only tools first.

See Setup and Accounts for the initial setup and Using MCP for the connection model. See MCP Skills when packages should expose reusable AI instructions.

Security Baseline

• Do not paste API tokens into prompts, chats, issue comments, or public logs.
• Store tokens in a local secret store or environment variable.
• Use one token per AI client or automation.
• Rotate tokens when a user changes role, a device is lost, or a workflow is no longer needed.
• Revoke tokens instead of reusing old credentials.
• Grant write permissions only when the workflow really needs write access.
• Review AI-created changes before publishing content.

See Security for operational rules.