Using MCP

QUIQQER's MCP endpoint lets AI clients call tools provided by installed QUIQQER packages. The endpoint authenticates the request, resolves the QUIQQER user from the token, and exposes tools according to installed providers and permissions.

Endpoint

The HTTP endpoint is:

https://www.example.com/mcp

Use the real host of the QUIQQER installation.

Authentication uses a bearer token:

Authorization: Bearer <QUIQQER_API_TOKEN>

Do not store the token directly in a shared configuration file. Prefer an environment variable or secret store.

Generic Client Configuration

MCP clients use different configuration formats. The important values are the server URL and the bearer token header.

Generic shape:

{
  "mcpServers": {
    "quiqqer": {
      "url": "https://www.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${QUIQQER_MCP_TOKEN}"
      }
    }
  }
}

Adapt the exact structure to the AI client. Keep the token in QUIQQER_MCP_TOKEN or an equivalent secret variable.

Client-specific pages for Codex, Claude, and other tools can build on this base configuration.

Codex CLI

For Codex CLI, add the QUIQQER MCP endpoint as a streamable HTTP server:

codex mcp add my-quiqqer-project \
    --url https://www.example.com/mcp \
    --bearer-token-env-var QUIQQER_MCP_TOKEN

Set QUIQQER_MCP_TOKEN in the shell environment before starting Codex. The environment variable contains the API token created for the dedicated QUIQQER AI user.

For the current terminal session, set the variable with export:

export QUIQQER_MCP_TOKEN="paste-the-api-token-here"

Then start Codex from the same terminal. To make the variable available in new terminal sessions, add the same export line to the shell startup file of the local user, for example ~/.bashrc or ~/.zshrc, and open a new terminal. Do not commit API tokens or store them in shared project files.

Use a meaningful server name for the first argument, for example the project or customer system name. The URL must point to the /mcp endpoint of the target QUIQQER installation.

Available Tool Areas

The exact tool list depends on installed packages and permissions.

Default MCP Server Resources

quiqqer/ai-mcp provides the MCP endpoint and baseline resources.

Resource	Purpose
quiqqer://mcp/session-user	Returns the current authenticated MCP session user.
quiqqer://mcp/server	Returns general information about the QUIQQER MCP server.
quiqqer://mcp/packages	Lists installed packages. Available for superuser sessions.
quiqqer://mcp/package/{vendor}/{package}	Returns information about one installed package. Available for superuser sessions.

Fallback tools for clients without resource support:

Tool	Purpose
quiqqer_mcp_session_user_get	Returns the current authenticated MCP session user.
quiqqer_mcp_server_get	Returns general MCP server information.

quiqqer/ai-mcp also includes simple diagnostic/example tools such as hello and calculator. Do not build production workflows around those example tools.

Core MCP Tools

Core tools are available when the user has the permission Can use the core MCP tools (quiqqer.core.mcp.canUse) and the normal project, site, media, or system permissions required for the action.

Core tool areas include:

Area	Examples
Projects	List projects and languages.
Sites	Read, search, create, update, activate, deactivate, copy, move, sort, and delete sites.
Media	Read, search, upload, update, activate, deactivate, delete, and create folders.
System	Clear selected caches when the dedicated permission is granted.

Project tools:

Tool	Purpose
quiqqer_projects_list	Lists projects with their languages.

Site tools:

Tool	Purpose
quiqqer_sites_list	Lists direct child sites for a project site.
quiqqer_sites_get	Returns one site by project, language, and ID.
quiqqer_sites_get_by_url	Resolves a public URL to project, language, and site data.
quiqqer_sites_search	Searches sites by name, title, short description, and content.
quiqqer_sites_create_child	Creates a child site below a parent site.
quiqqer_sites_update	Updates whitelisted site attributes.
quiqqer_sites_activate	Activates a site.
quiqqer_sites_deactivate	Deactivates a site.
quiqqer_sites_copy	Copies a site below another parent, optionally into another project language.
quiqqer_sites_copy_to_language	Copies a site to another language and can link language variants.
quiqqer_sites_add_language_link	Links one site to another site in a different language.
quiqqer_sites_move	Moves a site below another parent.
quiqqer_sites_sort	Sorts direct child sites below a parent site.
quiqqer_sites_set_type	Sets a site's type attribute.
quiqqer_sites_delete	Deletes a site and marks its children as deleted.

Media tools:

Tool	Purpose
quiqqer_media_get	Returns one media item by project and ID.
quiqqer_media_list	Lists direct children of a media folder.
quiqqer_media_search	Searches media by name, title, and short description.
quiqqer_media_create_folder	Creates a media folder below another media folder.
quiqqer_media_upload	Uploads a base64 encoded file into a media folder.
quiqqer_media_update	Updates whitelisted media attributes.
quiqqer_media_activate	Activates one media item.
quiqqer_media_deactivate	Deactivates one media item.
quiqqer_media_delete	Deletes one media item and moves it to the media trash.

System tools:

Tool	Purpose
quiqqer_cache_clear	Clears selected cache areas. Also requires Can clear the QUIQQER cache via MCP (quiqqer.core.mcp.clearCache).

Bricks MCP Tools

Bricks tools are available when quiqqer/bricks is installed and the user has the permission Can edit bricks via MCP (quiqqer.bricks.mcp) plus the normal Bricks permissions required for the action.

Bricks tool areas include:

Area	Examples
Brick types	List and inspect available brick types.
Bricks	List, read, create, update, and delete bricks.
Site brick areas	Read and set brick assignments for site areas.

Bricks tools:

Tool	Purpose
quiqqer_brick_types_list	Lists available brick types from installed bricks.xml files.
quiqqer_brick_types_get	Returns one brick type by its control identifier.
quiqqer_brick_areas_list	Lists available brick areas for a project template.
quiqqer_bricks_list	Lists existing bricks assigned to a project.
quiqqer_bricks_get	Returns one brick by its numeric brick ID.
quiqqer_bricks_create	Creates a new brick for a project.
quiqqer_bricks_update	Updates an existing brick.
quiqqer_bricks_delete	Deletes one or more bricks.
quiqqer_site_bricks_get_areas	Returns current brick assignments for a site.
quiqqer_site_bricks_set_area	Sets the brick assignment for one area on a site.

Package-Provided Tools

Packages can register additional MCP providers in package.xml:

<provider>
    <mcp src="\Vendor\Package\MCP\Provider"/>
</provider>

The provider class must implement the MCP provider interface exposed by quiqqer/ai-mcp and register tools with the MCP server builder.

See MCP Providers For Developers for package-level provider implementation.

Project And Language Context

QUIQQER projects can have multiple languages. MCP workflows should always be explicit about the target project and language.

Use the project list first when the client does not know the exact context. Then pass the project name and language to site or media tools.

Example context:

{
  "project": "default",
  "lang": "en",
  "siteId": 12
}

Do not let an AI client infer the language from a prompt when the operation can change content. Ask the client to read the current site first and confirm the target language before writing.

Example Workflow: Update A Site

1. List projects and languages.
2. Search or resolve the target site.
3. Read the site and check its current title, short text, type, active state, and URL.
4. Update only the intended attributes.
5. Read the site again and compare the result.
6. Clear cache only if the workflow requires it and the AI account has the dedicated permission.

For content editing, use a dedicated AI user with project/site edit permissions. Avoid using a superuser account for this workflow.

Example Workflow: Media And Bricks

1. List or search media in the target project.
2. Upload or update media if the AI account has media permissions.
3. List available brick areas for the target project/template.
4. List current bricks and brick assignments for the site.
5. Create or update a brick.
6. Assign the brick to the intended site area.
7. Read the site or brick assignment again before publishing.

Use the same project and language throughout the workflow unless the goal is a language copy or language link operation.