Mosaic MCP Server

The Mosaic MCP Server lets AI agents work with the services of a Mosaic environment. Agents such as Claude, ChatGPT, Claude Code, Codex and Visual Studio Code connect to it through the Model Context Protocol (MCP). They can then query and change the data of the managed services and your custom services, for example find movies without images, translate metadata or upload an image, as the signed-in user.

• Signed in as the user: the agent signs the user in with the identity providers of the environment, through the OAuth 2.1 authorization server of the Identity Service.
• Limited to what the user grants: the user selects which of their permissions the agent gets. Every Mosaic service checks these permissions on every call, as for any other request.
• Traceable: every change shows the user and the agent, for example Jane Doe (via Claude Code) in the updatedBy field.
• Managed and custom services: the agent can call the management GraphQL APIs of the managed services and of the custom services of the environment.

note

The Mosaic MCP Server is different from Mosaic Agent Skills. Mosaic Agent Skills run on your computer and help you develop Mosaic services and frontends. The Mosaic MCP Server is a hosted service that lets AI agents work with the data of an environment.

Prerequisites

• The AI agent is an OAuth client of the environment. See Manage OAuth Clients.
• The user has a management user account in the environment, with the permissions needed for the tasks.

Connect an AI Agent

Each environment has its own MCP server URL:

https://mcp.service.eu.axinom.net/<tenant-id>/<environment-id>

You find the tenant ID and environment ID in the Admin Portal, on the details page of the environment.

Add this URL as a remote MCP server (HTTP transport) in the AI agent. The agent then opens the sign-in of the environment in the browser. After signing in, the user selects the permissions to grant and clicks Allow.

Claude Code

claude mcp add --transport http mosaic https://mcp.service.eu.axinom.net/<tenant-id>/<environment-id>

Then run /mcp in Claude Code, select mosaic and Authenticate.

Codex

codex mcp add mosaic --url https://mcp.service.eu.axinom.net/<tenant-id>/<environment-id>
codex mcp login mosaic

Visual Studio Code

Add the server to .vscode/mcp.json in your workspace or to your user settings:

{
  "servers": {
    "mosaic": {
      "type": "http",
      "url": "https://mcp.service.eu.axinom.net/<tenant-id>/<environment-id>"
    }
  }
}

Claude and ChatGPT

Add a custom connector with the MCP server URL in the settings of the app. Their connectors run on the servers of their vendors, which reach the MCP server over the internet.

Other agents

Agents that publish a Client ID Metadata Document only need the URL. For agents without one, such as Cursor or Gemini CLI, add them as pre-registered OAuth clients and enter the generated client ID where the agent asks for an OAuth client ID.

tip

To use different permissions for different tasks, add the same URL more than once under different names, for example mosaic-read and mosaic-edit. Each connection has its own sign-in and its own granted permissions.

Tools

The MCP server offers two tools:

Tool	Description
list_mosaic_services	Lists the services that the agent can call, with the permissions the user granted for each.
mosaic_graphql	Runs a GraphQL query or mutation against the management GraphQL API of one of these services. Agents can use introspection to explore the schema of each service.

mosaic_graphql also uploads files for GraphQL Upload variables, for example images or ingest documents. A file can be given as an HTTPS URL, which the MCP server downloads, as base64 content or as text.

The tools are generic on purpose: they work with every service and every schema. Agents learn how to perform specific tasks, for example how to ingest and publish a movie, from the GraphQL schemas and from skills.

Which Services Agents Can Call

An agent can call a service when:

1. the service is enabled in the environment,
2. the user granted the agent at least one permission of that service, and
3. the MCP server knows the management GraphQL endpoint of the service.

Managed services: the MCP server knows the endpoints of the managed services that offer a management GraphQL API, such as the Identity, Video, Image, Localization and DRM services.

Custom services: the MCP server finds the endpoints of custom services in the configuration of their frontends (microfrontends) in the environment. The frontend <name>-workflows belongs to the service <name>-service, for example media-workflows to media-service. The MCP server uses the first of these frontend configuration values:

Configuration value	Example
MOSAIC_GRAPHQL_ENDPOINTS: a JSON object of endpoints by service ID	{"catalog-service": "https://catalog.example.com/graphql"}
A key ending with _ENDPOINT whose value is a GraphQL URL	FLEET_MANAGEMENT_ENDPOINT = https://fleet.example.com/graphql
<NAME>_MANAGEMENT_HOST and <NAME>_MANAGEMENT_HTTP_PROTOCOL	MEDIA_MANAGEMENT_HOST = media.example.com and https

Services created from the Mosaic Media Template already have <NAME>_MANAGEMENT_HOST in their frontend configuration, so they work without changes. A frontend can announce further services of the same deployment in MOSAIC_GRAPHQL_ENDPOINTS.

Endpoints of custom services must be HTTPS URLs of public host names. The MCP server doesn't follow redirects.

Limits

Limit	Value
GraphQL requests	About 120 per minute per user and environment
Files of one upload	20 MB in total
GraphQL response	10 MB
Duration of a GraphQL request	60 seconds

When an agent runs too many requests, the tool tells it how many seconds to wait.

Troubleshooting

What happens	Why, and what to do
The browser shows "This application is not allowed to connect to this environment."	The agent is not an OAuth client of the environment, or it is disabled. Add or enable it.
The browser shows that the application wants to return to an address that is not registered for it	The redirect URI of a pre-registered client is missing. Add it to the OAuth client.
list_mosaic_services doesn't list a service	The user didn't grant permissions for it, the service is not enabled, or its endpoint is unknown. Connect again and grant the permissions, or check the frontend configuration of a custom service.
A call fails with a permission error	The user didn't grant that permission, or no longer has it. Connect again and grant the permission.
The agent asks the user to connect again	The session ended: it expired, was deleted, its OAuth client was disabled or deleted, or the user was deactivated.

See Also

• OAuth 2.1 Authorization Server
• Manage OAuth Clients
• Identity and Access Management