Skip to main content
ModuleX integrations are connectors to external services. Each integration (for example github) ships a manifest plus a set of tools — the callable actions you run from a workflow’s Tool node or from the Assistant. The full set of integrations lives in one installable Python distribution, modulex-integrations, which the ModuleX backend loads at startup. This page is for people running or extending the ModuleX backend: it covers how integrations are discovered at runtime, how to install the package and the per-tool SDK dependencies you actually need, and how a tool call is authenticated either with ModuleX-managed credentials or your own key. If you only want to connect a service in the app, see Authentication & credentials and Connect an integration instead — you do not install anything for that.
The hosted ModuleX service already runs modulex-integrations for you. You install the package yourself only when you self-host the backend or develop integrations locally. To author a new integration, start at Build an integration.

​
How integrations load at runtime

Integrations are not configured by hand or read from a directory you point at. They are discovered through standard Python entry points in the group modulex.tools. Every integration in the package declares one entry point that maps its catalog name to its module:
pyproject.toml
[project.entry-points."modulex.tools"]
aws = "modulex_integrations.tools.aws"
github = "modulex_integrations.tools.github"
slack = "modulex_integrations.tools.slack"
# ... 175 entries total
At startup the backend enumerates this group, imports each module, and reads two required symbols from it:
​
manifest
IntegrationManifest
required
The integration’s manifest — name, display name, categories, actions, and auth schemas. Defined in manifest.py and re-exported from the package __init__.py. See the manifest & schema contract.
​
TOOLS
tuple[StructuredTool, ...]
required
A tuple of LangChain tool objects, one per action. See the @tool function contract.
The mapping key (for example github) is the integration’s catalog and credential name. The mapping value (for example modulex_integrations.tools.github) is the package module, not the tools module — the runtime appends .tools to it when it needs to import the callable (resolving to modulex_integrations.tools.github.tools).
1

Enumerate

The backend calls entry_points(group="modulex.tools") to list every registered integration.
2

Load

For each entry point it imports the module and reads manifest and TOOLS.
3

Cache

The resolved catalog is cached for the lifetime of the worker process. A newly installed package version is not picked up until you restart the worker.
Because the catalog is cached per process, upgrading modulex-integrations while a worker is running has no effect until that worker restarts. Restart all backend workers after installing or upgrading the package.

​
Two catalog sources

The runtime resolves tools from two places, and entry points are not the only one:
  • Package entry points — the modulex.tools group described above. This is the primary source and wins on a name collision.
  • Legacy on-disk JSON — a small set of integrations not yet migrated to the package, loaded from *_integration.json files in the backend. The Model Context Protocol connector (mcp_server) is handled this way rather than as a package entry point. See Custom MCP servers.
So “every tool comes from modulex-integrations” is almost true — treat the legacy JSON integrations as documented exceptions.
There are two distinct discovery mechanisms in this system, and they are not interchangeable. The runtime uses entry points (above). The documentation and CI pipeline that generates the integration catalog instead walks the filesystem for tools/*/manifest.py, using the entry-point table only as a cross-check. If you are reading manifests for tooling, match the mechanism to your goal.

​
Install the package

modulex-integrations requires Python 3.12 or newer. The base install pulls in only three core dependencies — pydantic, httpx, and langchain-core — which is everything most integrations need. 
pip install modulex-integrations
The backend pins an exact version of this package (it does not float with >=), because the manifest schema can change between minor versions and the runtime rejects unknown manifest fields at import time. When self-hosting, install the version that matches the backend you are running rather than the latest release.

​
Do not rely on install extras

The package declares an all extra and the README advertises per-tool extras such as [github,slack]. Do not use them. They do not work as written today:
The all extra is an empty list in the package, and there are no per-tool extras ([github], [slack], [aws], and so on are not defined). Installing them does not add any tool SDKs:
  • pip install "modulex-integrations[all]" installs only the three core dependencies — the same as the base install.
  • pip install "modulex-integrations[github,slack]" emits pip warnings like WARNING: modulex-integrations does not provide the extra 'github' and installs only the base package.
A script to auto-assemble these extras from each tool’s declared dependencies is planned but not implemented. Until it lands, treat [all] and per-tool extras as non-functional and install tool SDKs manually (below).
This limitation is also recorded in Known limitations and the Help known-limitations page.

​
Install tool SDK dependencies manually

Because extras are inert, the working path is: install the base package, then install whatever client SDK each integration you intend to use needs. Many integrations need nothing extra — they call their service over plain HTTP through the core httpx dependency. For example, both github and slack declare no additional dependencies. Others do need a vendor SDK. Each integration declares what it needs in a dependencies.toml file in its source directory:
src/modulex_integrations/tools/aws/dependencies.toml
dependencies = ["boto3>=1.34.0"]
Install those yourself. For an AWS-backed workflow, for example: 
pip install modulex-integrations boto3
There is no REST endpoint that runs a tool directly. Tools execute only inside workflow runs and Assistant/Composer turns. Installing the package makes the catalog available to the backend; you call individual tools through the Tool node, the Assistant, or the AI Composer.

​
Managed usage vs bring-your-own-key

Whether a tool needs an SDK installed is separate from how it is authenticated and billed. Every tool call resolves a credential for the integration in your organization, and that credential is one of two kinds.

ModuleX-managed

The call runs through a ModuleX-provisioned key from a managed pool. Usage is metered in credits and is subject to the billing gate. The managed providers appear on the wire as modulexai (models) and modulexdb (knowledge); managed tool calls draw from your credit balance.

Bring your own key (BYOK)

You connect your own provider account. Usage is billed directly by that provider with no ModuleX markup, and BYOK calls are not charged in ModuleX credits — they are tracked for analytics only. BYOK is available on every plan; there is no entitlement that gates it.
The runtime injects the resolved credential into the tool call internally, so the model and the tool function never see raw secrets. The behavior differs by credential kind:
​
ModuleX-managed credential
metered in credits
Before the call runs, the runtime checks the organization’s credit limit (without recording yet). If the monthly budget is exhausted and no wallet overage is available, the call is denied. On success it records the per-call tool cost. See Credits & metering.
​
BYOK credential
not credit-limited
The runtime decrypts your stored credential, refreshes the OAuth2 token if it is close to expiry, and runs the call. There is no credit check or credit charge — only usage tracking.
ModuleX-managed tool calls are part of the live billing gate. When the credit limit is exhausted, a managed call is denied rather than running. Plan for this in any workflow that depends on managed tool usage. BYOK calls are never credit-gated.
For how a tool resolves credentials, refreshes OAuth2 tokens, and maps auth into the call, see Credentials & OAuth2 and Authentication & credentials. For model and knowledge providers specifically, see LLM providers and Knowledge providers.

​
Verify the catalog loaded

After installing the package and restarting your workers, confirm the integrations you expect are present. The catalog the backend exposes reflects the entry points found at startup.
🎬 MEDIA PLACEHOLDER · MX-MEDIA-4010 · [SCREENSHOT] [SCREENSHOT_DESCRIPTION]: The integrations catalog in the ModuleX app after the package has loaded, showing connected and available integrations. [SCREENSHOT_DETAILS]: Capture the integrations catalog page in the live ModuleX app. Show the grid of integrations with a few connected (credential present) and the rest available to connect. Dark theme, full-width, no personal data. Highlight that the count reflects the installed package, not a hardcoded list.
If an integration you expect is missing, check, in order:
The catalog is cached per process. Restart all backend workers after installing or upgrading modulex-integrations.
The backend pins an exact version. A mismatched install can fail to import a manifest with an unknown field, because the schema rejects unknown fields at import time. Install the version that matches your backend.
An integration whose dependencies.toml lists a vendor SDK will fail to load its tools if that SDK is missing, because extras do not install it for you. Install the SDK manually (see above). The integration’s manifest may still appear while individual actions fail to load.
A few integrations (such as mcp_server) load from legacy on-disk JSON, not from the package entry points. See Custom MCP servers.

​
Next steps

Authentication & credentials

Connect a service with an API key or OAuth2 and store the credential.

Browse the catalog

See every integration ModuleX can connect to, grouped by category.

Use a tool in a workflow

Call an integration’s action from the Tool node.

Build an integration

Author your own integration and expose its tools.