> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/v4.7-en/the-factory/deployer-des-apps-et-des-tools.md).

# Deploy Apps and Tools

Create and deploy your AI applications and tools directly on the platform via The Factory.

{% hint style="info" %}
The terminology of The Factory  has evolved:

* The Factory  for Agents becomes **The Factory**,
* the **Agent Apps** and **Agent Tools** become the **Apps** and **Tools** — the whole being referred to by the term **Apps**
* the **AI Contexts** become the **Agents**.
  {% endhint %}

The Factory  makes it possible to **create, deploy and administer** applications - **Apps** and MCP servers - **Tools** within the Cleyrop platform.

It provides a secure, standardized framework for developing applications and extensions based on AI models and external connectors.

***

## Understanding the types of apps

### Application - App

An App is an **application** standalone deployed on Cleyrop.

It has a **dedicated URL** and works independently of the Druide. It can be used to expose an interactive user interface, for example a Gradio dashboard or a mini processing app, an ML model, an API...

Apps can be used from outside via a whitelisted IP with the app URL or from the Cleyrop services platform thanks to the internal URL: a **Dataflow, an App, a DevSpace** or a **Codelab notebook.**

### MCP server - Tool

A Tool in Cleyrop corresponds to a **MCP server** declared and managed from The Factory  .

It allows extending the **Druide's capabilities** by giving it access to external services, APIs or internal tools. It is also available to be used in a **Dataflow, an App** or a **Codelab notebook.**

👉 For developers wishing to create their own tools, consult the official MCP documentation: <https://modelcontextprotocol.io/docs>

**Key principles**

* Each Tool exposes a **MCP-compatible endpoint** : the platform calls your server with requests `POST <service URL>/mcp`, **without a trailing slash**. Expose your MCP server on this exact path (`/mcp`), with the protocol's HTTP transport.
* The tools defined in the server can be **enabled or disabled** from Le Druide.
* The **user variables** (e.g., API keys, business filters) can be configured directly in the assistant or at the app listing level.
* Communication happens in **real time** : the assistant calls the server, performs the action, then returns the response to the user.

**Usage examples**

* Automatic document generation (Word, PDF...).
* Sending emails or notifications.
* Data extraction from internal or external APIs.
* Interaction with business tools (Jira, Lucca, CRM...).

**Best practices for Tool developers**

To ensure smooth integration and optimal use of your tools:

* By default, all Tools are enabled in Le Druide: **describe precisely** the function of each tool in its documentation.
* Clearly specify the expected inputs and outputs: types, formats, constraints, possible values, return structure, JSON format, key fields.
* Respect the **schema consistency** between tools to facilitate their combination in the same context.
* **Test your tools in Le Druide** before sharing them with end users.

**Retrieve a user variable in an MCP Tool**

When a user configures a Tool user variable (via the configuration gear in the Druide, or via the Tool detail page), this value is not exposed to the MCP server as an environment variable. Instead, the Druide passes the user variables in the headers of each HTTP request sent to the Tool. Each tool call therefore includes the variable(s) specific to the user who triggered it.

To retrieve these values in your Tool code, use `get_http_request()` (provided by FastMCP), then read the desired header in `request.headers`. The header name matches the user variable name.

**Code example:**

```python
"""Utility for extracting user access token from FastMCP request headers."""

import logging
from typing import TYPE_CHECKING, Optional

from fastmcp.server.dependencies import get_http_request

from src.config.corpus_mcp_config import get_corpus_mcp_config

if TYPE_CHECKING:
  from starlette.datastructures import Headers
  from starlette.requests import Request

logger = logging.getLogger(__name__)


def get_user_access_token() -> Optional[str]:
  """Extract the user access token from the request headers."""
  request: Request = get_http_request()
  headers: Headers = request.headers
  return headers.get(get_corpus_mcp_config().user_access_token_header)
```

#### Making a Tool usable by Le Druide

Once the Tool instance is deployed, the platform queries your server to retrieve the list of its tools. For this discovery to succeed:

* **Called URL** : `http://<technical name of the instance>.<namespace>.svc.cluster.local:<exposed port>/mcp`. The technical name and namespace are indicated in the instance sheet; the port is the one declared at the Deployment step.
* **Exact path `/mcp`**, without a trailing slash: the platform does not follow redirects. A server that responds only on `/mcp/` returns a 404 error and exposes no tool.
* **Discovery only at deployment** : the tool list is read when the instance is deployed or updated, never periodically. If your server was not ready at that time, or if you change its tools or its path, **redeploy the instance** to relaunch discovery.
* **Health check without authentication** : the health check path declared at the Deployment step must respond without a token.

{% hint style="warning" %}
If discovery fails, the Tool still appears as deployed and activatable in Le Druide, but its tab **Tools** is empty and Le Druide cannot execute anything. Check the path `/mcp`, the exposed port and the instance application logs, then redeploy it.
{% endhint %}

#### Native Cleyrop Tools

Cleyrop provides several **native Tools**, visible in the Apps and Tools list just like yours:

* **Cleyrop Corpus** — allows[querying a document corpus](/docs/v4.7-en/le-druide/interroger-un-corpus-de-documents.md) from Le Druide
* **Cleyrop Dataset** — allows[querying datasets](/docs/v4.7-en/le-druide/interroger-des-datasets.md) from Le Druide
* **Cleyrop Internet** — allows performing internet searches from Le Druide

Unlike your own Apps and Tools, only the action **Configure** (token management) is accessible on their detail page.

Native Tools can also be called from your own Apps, DevSpaces or notebooks via their internal URL: see [Use Cleyrop Dataset from your own apps](/docs/v4.7-en/le-druide/interroger-des-datasets.md#utiliser-cleyrop-dataset-depuis-vos-propres-apps).

{% hint style="info" %}
The tool **Cleyrop Internet** does not require token configuration.
{% endhint %}

## Create an App

Creation happens in two steps:

* first the App creation (name and description)
* then the configuration of images and instances.

### **Step 1: Create the App**

1. Go to **The** **Factory** → Apps
2. Click on **Create**
3. Fill in:
   * **Name** : unique identifier of your App (max 50 characters, duplicates not allowed)
   * Enable **Mark this app as a Tool** if it is an MCP server
   * **Description** : free text supporting markdown (headings, bold, italics, lists, links)
4. Select, if needed, the **Apps and Tools** that your App will be able to call from the list of apps available on the platform. By default, no access is configured.
5. Click on **Create**

At this stage, no image or instance is configured.

<div align="left"><figure><img src="https://4159280578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMHNFH6aA4j5ucH4XFBXy%2Fuploads%2Fgit-blob-5337e36066260ed08475dd5e4549dd0f45651b82%2Fimage.png?alt=media" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://4159280578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMHNFH6aA4j5ucH4XFBXy%2Fuploads%2Fgit-blob-e30b8ca79e886b8e5db41a2ece140384657f3a37%2Fimage.png?alt=media" alt="" width="563"><figcaption></figcaption></figure></div>

### **Step 2: Configure images and instances**

From the App sheet, you can:

* [**Create and build an image**](/docs/v4.7-en/the-factory/gerer-les-images.md) from a Git repository in the Cleyrop internal registry
* [**Create and deploy an instance**](/docs/v4.7-en/the-factory/gerer-les-instances.md) from an image in the internal registry or an external registry

{% hint style="info" %}
The first instance created automatically becomes the App's main instance.
{% endhint %}

### Instance startup and outbound network access

At deployment, the platform waits for your application to respond to its **Health check** (TCP or HTTP, configured at the Deployment step). This startup delay is about **2 minutes** and does not depend on the **deployment timeout** of the instance: an application that does not respond within this time is restarted and the deployment fails, even if the image is correct.

Outbound traffic from an instance is **closed by default**, except to platform services and the internet ports declared at the Deployment step (currently, 443 for HTTPS and 22 for SSH). A connection to an unauthorized destination is not refused: it **remains pending** until it times out. A blocking network call at startup (downloading a model, connecting to an external database, installing dependencies) can therefore prevent the application from responding to the health check in time.

For a reliable startup:

* Expose the health check path **before** long initializations, and run them in the background or on the first request.
* Embed dependencies and models in the image rather than downloading them at startup (for Hugging Face models, set `HF_HUB_OFFLINE=1`).
* If your application needs to connect to an external service, declare the required port at the Deployment step and check access in the application logs.

## Using an App

You can find the list of apps usable from Applications > Apps/Tools. You can filter them by Status.

* An App can be opened directly from its card or via its URL on its detail page.
* Successfully deployed Tools can be used directly from Le Druide. It is possible to enable or disable each tool present on each deployed Tool.

{% hint style="warning" %}
Apps are accessible through the **whitelisted IPs**
{% endhint %}

<div><figure><img src="https://4159280578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMHNFH6aA4j5ucH4XFBXy%2Fuploads%2Fgit-blob-976214171a30d847dcf52bd4fd63b4f90b372b53%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://4159280578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMHNFH6aA4j5ucH4XFBXy%2Fuploads%2Fgit-blob-39e2269c93a5926ad2ff78f35b978dc07ff814bb%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

Some Tools need to be configured to be used; you will then see a button appear <i class="fa-gear">:gear:</i> on the card or detail page.

You will then see the list of environment variables to fill in so you can use the Tool with your credentials.

<figure><img src="https://4159280578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMHNFH6aA4j5ucH4XFBXy%2Fuploads%2Fgit-blob-d11d9cf937e1de6e1fd6b3fcdbf1a9502c4911e3%2Fimage.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

### View the tools of a Tool

You can access the complete list of tools offered by a Tool, as well as their input and output parameters, to understand the use cases covered.

In a Tool's detail page, a Tools tab automatically appears. This tab is not present on Apps.

It allows you to consult the **list of tools** and for each available tool:

* **Description** : what the tool does, and when to use it.
* **Input parameters** : the expected fields, their type and their role.
* **Output parameters** : the structure of the returned data.

This view allows the user to quickly understand how to use a Tool in Le Druide or during advanced development.

### Access Apps from a DevSpace

Apps created in The Factory  can be accessed from a DevSpace to facilitate development and testing.

**Configure access**

1. When creating or modifying a DevSpace, go to the "Apps" section.
2. Search for your App by name.
3. Check the Apps that the DevSpace should be able to connect to.
4. Save the changes.

### Monitor resources

A summary of reserved resources is accessible from the button **Used resources** at the top right of The Factory  . It displays, in CPU and RAM, the **Request** (guaranteed resources) and the **Limit** (ceiling) of all Apps, Tools and DevSpaces deployed on your environment. Details and recommendations are described in [Monitor resources](/docs/v4.7-en/administration/surveiller-les-ressources.md).

<figure><img src="https://4159280578-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMHNFH6aA4j5ucH4XFBXy%2Fuploads%2Fgit-blob-a032731e174a4b6be2e682413ebfda8450d556b1%2F4.7-factory-resources-used.png?alt=media" alt="Encart Ressources utilisées de La Fabrique" width="420"><figcaption></figcaption></figure>

***

## Best practices

* Use lightweight Docker images, tested locally and compatible **linux/amd64**.
* Give explicit names and document variables to make maintenance easier.
* Regularly check the logs and use automatic rollback in case of deployment failure.
* Remember to modularize your apps: a model, an embedding module, a business tool → one clear Tool.