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.

Authenticated requests use an OAuth bearer access token:

Authorization: Bearer <OAUTH_ACCESS_TOKEN>

OAuth-capable clients can obtain and refresh this token automatically. Clients without an interactive OAuth flow can use a manually created QUIQQER API token.

Automatic OAuth Authorization

Interactive MCP clients such as Codex can discover the OAuth server from the MCP endpoint. No API token has to be created or copied manually.

The authorization flow is:

1. The client connects to /mcp without a token.
2. QUIQQER returns the URL of the MCP Protected Resource Metadata.
3. The client discovers the OAuth authorization, token, revocation, and dynamic registration endpoints.
4. The client registers itself as a public OAuth client and creates a PKCE challenge.
5. The browser opens the QUIQQER login and consent pages.
6. The user logs in with a normal QUIQQER account and reviews the MCP resources, resource templates, tools, and prompts available to that account.
7. After approval, QUIQQER redirects the browser to the client's local callback.
8. The client exchanges the authorization code for access and refresh tokens and uses them for subsequent MCP requests.

The consent page uses the language and identity of the QUIQQER project serving the MCP endpoint. The permissions of the user who approves the request determine which MCP functions can be used.

The callback can use a loopback address such as http://127.0.0.1:<port>. This is expected for a locally running client: the browser returns the authorization result to that client on the same computer. The callback is not a QUIQQER server address.

Dynamic client registration must be enabled in the OAuth settings. It is enabled by default in current versions. If it was disabled, open the OAuth settings in the QUIQQER administration and enable Dynamic client registration.

Manual Bearer Token Configuration

For an unattended integration or a client without OAuth discovery, create a QUIQQER API token and pass it as a bearer token. 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.

Codex CLI

Add the QUIQQER MCP endpoint as a streamable HTTP server:

codex mcp add my-quiqqer-project --url https://www.example.com/mcp

Codex detects OAuth support and opens the browser flow automatically. Log in to QUIQQER, review the MCP functions shown on the consent page, and select Allow access. Codex then completes the authorization-code exchange and manages the resulting OAuth tokens.

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.

To use a manually created API token instead, add the bearer-token environment variable:

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.

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/skills	Lists available MCP skills from installed packages.
quiqqer://mcp/skill/{name}	Returns one MCP skill by name.
quiqqer://mcp/skill/get/{name}	Returns one MCP skill by name through an explicit get-style resource.
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_skill_list	Lists available MCP skills.
quiqqer_skill_get	Returns one MCP skill by name.
quiqqer_mcp_skill_list	Lists available MCP skills through an MCP-namespaced alias.
quiqqer_mcp_skill_get	Returns one MCP skill through an MCP-namespaced alias.

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

MCP Skills

quiqqer/ai-mcp 1.5.0 and later can expose package-provided MCP skills. Skills are reusable Markdown instructions that clients can discover and load before working on package-specific tasks.

Use quiqqer://mcp/skills or quiqqer_mcp_skill_list to discover skills. Use quiqqer://mcp/skill/{name} or quiqqer_mcp_skill_get to load one skill.

See MCP Skills for the file format, provider registration, and package integration.

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 And Skills

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.

Packages can also register Skill Providers:

<provider>
    <mcpSkill src="\Vendor\Package\MySkillProvider"/>
</provider>

The Skill Provider registers Markdown skill files with the MCP skill repository.

See MCP Providers For Developers for package-level provider implementation and MCP Skills for Skill Provider details.

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.