Connector plugins¶

Connector plugins add tools, prompts, and resources to Umbod. A plugin is a Python distribution packaged in a plugin-bundle container image.

For account ownership, administrator publication, and user sign-in, see Shared and Personal connectors. Personal account connections are distinct from installing a connector plugin.

Start with the SDK CLI¶

Install the umbod SDK as a uv tool, then use these commands in a connector project:

Command	Purpose
`umbod connectors init --name ID --module PACKAGE.MODULE`	Preview a generated Hello World connector and its package entry point; add `--apply` to write both.
`umbod connectors check`	Check entry-point metadata offline without loading connector code.
`umbod connectors check --target RELEASE`	Check the declared SDK dependency against SDK-version metadata from published core and builder images. For older, unlabeled releases, use `--sdk-version VERSION` after reading the builder image's installed SDK version.
`umbod skills list` / `umbod skills install draft-agent-connector --harness agents`	Optionally give a coding agent the bundled connector-authoring guidance.

See Build a connector for the complete Hello World walkthrough, including project setup, CLI checks, image validation, and deployment. The SDK CLI does not build or publish a plugin image.

Lifecycle¶

A connector passes through four separate states:

Installed: the configured plugin image materializes the connector distribution into the Umbod core Pod.
Available: the connector ID appears in plugins.availableConnectorIds in the Helm values.
Configured: an administrator supplies valid connector settings in Umbod.
Published: an administrator publishes the connector, activates its capabilities, and grants the required group permissions.

Installing a plugin image does not expose every connector in that image. The Helm availability list is the deployment-level allow-list. Configuration, publication, capability activation, and group permissions remain administrator actions.

flowchart LR
    Image[Plugin-bundle image] --> Materialize[Materialize /plugins]
    Materialize --> Validate[Validate package and SDK compatibility]
    Validate --> Available[Deployment-available connector]
    Available --> Configure[Configure and check]
    Configure --> Publish[Publish and activate]
    Publish --> Authorize[Grant group permissions]
    Authorize --> Agent[Agent capability]

Runtime model¶

The Helm chart runs the plugin image as an init container. The image copies its bundle into a shared volume, and the matching Umbod core image validates the bundle before the API and MCP containers start. Both services then load the same connector packages read-only.

The core image supplies the Connector SDK. A plugin bundle contains connector code, its runtime dependencies, and Python distribution metadata, but it must not contain another copy of the SDK.

Warning

Connector plugins are trusted Python code. They run inside the Umbod API and MCP processes with the processes' filesystem, network, and environment access. Plugins are not sandboxed or isolated from Umbod or from each other. Review and control every plugin image installed in an environment.

Current limitations¶

One plugin-bundle image can be configured for an Umbod release. Combine all required connector distributions into that bundle.
Plugins share one Python runtime and dependency namespace with Umbod and each other.
Connector-builder and core image tags must match. Helm chart versions are selected separately and need not match image tags.
Plugin images should use immutable tags. Floating tags such as latest are unsupported.
Structural validation does not verify credentials, external service availability, or the safety of connector operations.

Continue with Build a connector to package and deploy a connector using the public base image.