Connectors¶

The Connectors page defines the external systems, services, APIs, databases, applications, and endpoints that a Unitt agent needs to access during execution. Users specify what the Unitt should connect to, why the connection is needed, what permissions are required, and how the connection should be used within the runtime workflow. This step also creates the initial user vault, where external connection references, credentials, secrets, access scopes, and permission boundaries are organized before runtime execution begins.

Connectors are informed by the active agentic-integration research lineage, including the Model Context Protocol 2025-11-25 specification and 2026 MCP roadmap, the Official MCP Registry (9,400+ servers by mid-April 2026), the MCPB bundle format, OAuth 2.1 + PKCE as the agent connector baseline, DPoP token binding (RFC 9449), Workload Identity Federation, HashiCorp Vault namespaces, AWS Secrets Manager hierarchical scoping, the OWASP MCP Security Cheat Sheet, tool-poisoning mitigations after CVE-2025-54136 MCPoison, and the MCP Gateway / Registry pattern. Selection criteria for connector configuration are documented in Reference › Research › Assembly Connectors.

Note

If you already have a credential vault defined, you can reuse it as needed. Associate the vault with the agent by clicking the "Search Vaults" button in the top right corner. Then select the vault, or individual credential you would like to use.

Connector Definition¶

Each connector should define the target system, endpoint, authentication method, permission scope, intended usage, and operational limits. The connector will include a corresponding markdown file that explains how the Unitt agent is expected to use the connection, when it should be called, what data it may access, and what actions it is allowed to perform. This keeps connection behavior explicit, reviewable, and reusable across workflows. All markdown and configuration are directly editable on the page as well if any issues occur during textual generation.

flowchart LR
    CD[Connector Definition] --> TS[Target System]
    CD --> EP[Endpoint]
    CD --> AM[Authentication Method]
    CD --> PS[Permission Scope]
    CD --> IU[Intended Usage]
    CD --> OL[Operational Limits]
    CD --> UM[Usage Markdown]

    PS --> VAULT[Tenant-Scoped Vault]
    AM --> OAUTH[OAuth 2.1 + PKCE]
    AM --> WIF[Workload Identity Federation]

    classDef stage fill:#ffd541,stroke:#222021,color:#222021
    class CD,TS,EP,AM,PS,IU,OL,UM,VAULT,OAUTH,WIF stage

CLI-First Posture¶

The platform's preferred connector substrate is a first-class CLI tool wherever a robust command-line interface exists for the target system. CLIs are the most cost-efficient and most auditable connector shape: they run inside the Shell and Sandbox tools with deterministic argument schemas, produce structured stdout / stderr output that the runtime can parse and validate, integrate cleanly with CodeAct composition, inherit identity and credentials from short-lived environment-injected secrets, and require no additional protocol surface to govern. For the majority of cloud, source-control, container, database, and infrastructure systems, the vendor-maintained CLI (aws, gcloud, az, gh, glab, kubectl, docker, psql, redis-cli, terraform, etc.) is more mature, more capable, and more predictable than any wrapper protocol.

flowchart LR
    AGT[Agent] --> CHK{CLI Available + Mature?}
    CHK -- yes --> CLI[CLI Tool via Shell / Sandbox]
    CHK -- no --> MCP[MCP Server Fallback]
    CLI --> ARG[Strict-Mode Arg Schema]
    CLI --> ENV[Env-Injected Short-Lived Creds]
    CLI --> OUT[Structured stdout / stderr]
    OUT --> VAL[Output Validator]
    MCP --> MGW[MCP Gateway]
    VAL --> AGT
    MGW --> AGT

    classDef stage fill:#ffd541,stroke:#222021,color:#222021
    class AGT,CHK,CLI,MCP,ARG,ENV,OUT,VAL,MGW stage

The platform's selection rule is: pick the CLI when a vendor-maintained CLI exists, is well-documented, has stable argument semantics, and supports machine-readable output (--output json, --format json, or stable stdout parsing). Fall back to other substrates only when the CLI surface is missing, immature, requires interactive prompts that resist automation, or the workload genuinely benefits from a different transport.

MCP Posture¶

When no first-class CLI is available, or when a managed Model Context Protocol server provides materially better governance and discovery, the platform falls back to MCP as the second-preferred substrate. MCP servers expose Tools, Resources, and Prompts behind a uniform protocol; the Official MCP Registry exceeded 9,400 servers by mid-April 2026 (a 7.8× year-over-year expansion), and 78% of enterprise AI teams report at least one MCP-backed agent in production. Managed MCP servers are first-party from Snowflake (Cortex Agents), Databricks (Unity-Catalog governed Genie + Vector Search), ServiceNow (native MCP in Zurich + A2A), Salesforce (Agentforce MCP), and SAP (via partner gateways).

MCP is the right choice when the target system has no usable CLI, when the managed MCP server already wraps multi-step workflows the platform would otherwise script itself, when the target is a SaaS surface that primarily exposes a hosted API rather than a CLI, or when discovery and capability negotiation across many agents and many servers is required.

flowchart LR
    NEED[New Connector] --> Q1{CLI Mature?}
    Q1 -- yes --> CLI[CLI Tool]
    Q1 -- no --> Q2{Managed MCP Available?}
    Q2 -- yes --> MCP[MCP Server]
    Q2 -- no --> Q3{Has REST / gRPC / GraphQL?}
    Q3 -- yes --> WRAP[Wrap In MCP-Shaped Declaration]
    Q3 -- no --> WHK[Webhook Ingest]
    CLI --> RDY[Connector Ready]
    MCP --> RDY
    WRAP --> RDY
    WHK --> RDY

    classDef stage fill:#ffd541,stroke:#222021,color:#222021
    class NEED,Q1,Q2,Q3,CLI,MCP,WRAP,WHK,RDY stage

Fallback Binding Shapes¶

When neither a CLI nor a managed MCP server is available, the platform falls back to four binding shapes wrapped in an MCP-shaped declaration so the fabric sees a uniform tool surface regardless of underlying transport: REST / OpenAPI as the default, gRPC for low-latency internal services, GraphQL for typed graph traversal, and webhooks for push-based event ingest.

Authentication¶

OAuth 2.1 with PKCE is the 2026 baseline for agent connectors because agent runtimes are public clients with no secure secret storage. The pattern is short-lived per-agent access tokens (minutes), narrow scopes per tool, and RFC 8693 token exchange to swap a principal token for a task-scoped agent token. DPoP (RFC 9449) cryptographically binds tokens to a per-client keypair via a JWT proof signed on every request, defeating bearer-token replay; the consensus 2026 stance is "DPoP is when, not if." For machine-to-machine, Workload Identity Federation lets cloud workloads exchange their native attestation for short-lived STS tokens with no exported keys.

flowchart LR
    AGT[Agent] --> VLT[Vault Namespace]
    VLT --> ASRT[Workload Assertion JWT / OIDC]
    ASRT --> STS[STS / RFC 8693 Token Exchange]
    STS --> DPOP[DPoP-Bound Access Token]
    DPOP --> MGW[MCP Gateway]
    MGW --> MSV[MCP Server]
    MSV --> EXT[External System]

    classDef stage fill:#ffd541,stroke:#222021,color:#222021
    class AGT,VLT,ASRT,STS,DPOP,MGW,MSV,EXT stage

Credential Vaults¶

Credentials live outside the agent at all times. Per-tenant scoping is mandatory under OWASP LLM08:2025 and the OWASP Agentic Top 10 blast-radius guidance. The platform supports four vault substrates:

Vault	Pattern
HashiCorp Vault Enterprise namespaces	One namespace per tenant or per agent fleet; Vault Agent injector annotates pods with `vault.hashicorp.com/namespace=<tenant>`.
AWS Secrets Manager	Hierarchical naming `/{env}/{tenant}/{connector}/{secret}` plus ABAC on session tags.
Azure Key Vault	Tenant ID + RBAC; ML-pipeline integration as of 2026.
GCP Secret Manager	IAM bindings + notification-driven rotation.

Connector Validation¶

Validation in mature agent platforms is a three-stage probe; the platform performs all three before any connector is marked ready.

flowchart LR
    REG[Register Connector] --> CRED[Resolve Credential]
    CRED -->|miss| FAIL[failed]
    CRED -->|hit| PRB[Probe: Auth + Reachability]
    PRB -->|401/403| PDN[permission-denied]
    PRB -->|2xx| DRY[Dry-Run No-Op Call]
    DRY -->|policy block| RRV[requires-review]
    DRY -->|success| PCH[Permission Check]
    PCH -->|insufficient| PDN
    PCH -->|ok| RDY[ready]

    classDef stage fill:#ffd541,stroke:#222021,color:#222021
    class REG,CRED,PRB,DRY,PCH,RDY,FAIL,PDN,RRV stage

Canonical status states and their remediation paths are:

State	Meaning	Remediation
`ready`	All probes pass; connector usable.	None.
`pending`	Probe in flight.	Wait, then re-probe.
`failed`	Reachability or core auth probe failed.	Re-credential, re-probe.
`expired`	Token TTL elapsed.	Refresh-token rotation.
`permission-denied`	Auth ok, scope insufficient.	Re-consent / scope adjustment.
`requires-review`	Manual approval gate (e.g., tool-poisoning detection or unsigned descriptor).	Route to human review.

The platform applies Kubernetes server-side dry-run semantics where supported (a no-op call against the real endpoint that exercises admission and policy without persistence) and falls back to a synthetic dry-run otherwise.

Common Connectors¶

Connectors define the external systems, communication platforms, APIs, databases, applications, and services that an agent can interact with during runtime execution. These connectors allow the runtime to retrieve data, communicate with users, automate workflows, access infrastructure, interact with development systems, and coordinate actions across external platforms. The recommended design pattern is to begin with a minimal trusted connector set and expand access only as workflow requirements evolve.

Communication Connectors¶

Slack¶

Runtime messaging, alerts, workflow coordination, approvals, and operator communication.

Discord¶

Community communication, automation workflows, notifications, and runtime interaction.

Microsoft Teams¶

Enterprise communication, approval routing, workflow coordination, and reporting.

Telegram¶

Lightweight runtime messaging, alerts, notifications, and command interaction.

Email / SMTP¶

Outbound messaging, notifications, reports, approvals, and automated communication workflows.

Twilio¶

SMS messaging, voice communication, verification flows, and notification systems.

X / Twitter¶

Social posting, monitoring, trend analysis, and engagement workflows.

LinkedIn¶

Prospecting, professional outreach, company analysis, and business intelligence workflows.

Reddit¶

Community analysis, sentiment tracking, research, and monitoring workflows.

GitHub¶

Repository access, pull requests, CI / CD workflows, code analysis, and automation pipelines.

GitLab¶

Source control, deployment automation, repository management, and workflow orchestration.

Jira¶

Task management, ticket workflows, sprint coordination, and operational tracking.

Notion¶

Documentation, workflow state management, operational knowledge, and collaborative runtime memory.

Cloud & Infrastructure Connectors¶

AWS¶

Infrastructure orchestration, S3 storage, ECS / EKS deployments, IAM access, and operational automation.

Google Cloud¶

Cloud infrastructure, storage, deployment workflows, and runtime services.

Azure¶

Enterprise cloud infrastructure, authentication systems, deployment orchestration, and automation.

Cloudflare¶

DNS management, Workers deployment, edge networking, and security workflows.

Kubernetes¶

Cluster orchestration, workload deployment, scaling, and runtime infrastructure management.

Docker¶

Container management, image builds, runtime execution, and deployment automation.

Data & Storage Connectors¶

PostgreSQL¶

Structured runtime data, workflow persistence, operational storage, and audit systems.

Redis¶

Caching, queues, distributed state coordination, and transient runtime storage.

S3-Compatible Storage¶

Object storage, artifacts, runtime snapshots, logs, and workflow assets.

Elasticsearch / OpenSearch¶

Search indexing, observability, operational analytics, and runtime query systems.

Neo4j / Graph Databases¶

Relationship mapping, memory graphs, workflow dependency analysis, and reasoning systems.

Vector Databases¶

Embedding retrieval, semantic search, memory recall, and retrieval-augmented workflows.

Browser & Automation Connectors¶

Playwright¶

Browser automation, validation workflows, scraping, testing, and runtime interaction.

Selenium¶

Browser control, automation testing, and workflow interaction systems.

Puppeteer¶

Web automation, scraping, workflow validation, and runtime browsing tasks.

System & Runtime Connectors¶

SSH¶

Remote execution, infrastructure management, deployment workflows, and operational maintenance.

REST APIs¶

External service integration, runtime communication, and operational automation.

Webhooks¶

Event ingestion, runtime triggers, workflow activation, and distributed coordination. Inbound webhooks verify HMAC-SHA256 signatures with constant-time compare, replay-window check (timestamp tolerance ~5 minutes), and per-source key rotation; the gateway endpoint enqueues to Kafka / Pub/Sub / SQS in milliseconds and an agent worker consumes for back-pressure and durable replay.

CLI-Based Runtime Connectors¶

Direct interaction with local binaries, infrastructure tooling, automation frameworks, and runtime utilities.

MCP Gateway And Tool Poisoning Defense¶

Every connector call routes through an MCP Gateway that enforces allowlists, propagates OAuth / OIDC tokens, signs each tool descriptor, logs every allow / deny / mutate with a cryptographic trace ID, and severs the session if a server attempts to register an unapproved tool mid-run. Tool poisoning (the CVE-2025-54136 MCPoison class) exploits the fact that MCP tool descriptions ride into the model context with ambient authority; the platform's mitigation is content-hash pinning of approved descriptors, re-approval on any descriptor diff, provenance signing, and stripping hidden instructions before they reach the model.

Operational Limits¶

Per-connector resilience uses three layers: token-bucket rate limits (per-agent + per-tenant, 429 + Retry-After), circuit breakers (Closed → Open on error or cost-velocity threshold → Half-Open probe), and retry budgets with exponential backoff plus jitter. Failure handling enumerates retry (transient 5xx / 429), fallback (alternate connector / cheaper model / cached result), skip (non-critical step), escalate (human approval after N retries), and terminate (cost kill-switch + dead-letter queue with full context for replay). Retry budgets are enforced outside the agent loop to prevent quadratic context growth.

Connector Testing¶

The Connectors page includes a final validation step that confirms each connection is correctly configured before it is used by the runtime. If you need to specify a specific endpoint to validate, ensure that you include additional information via the prompt that specifies how you would like the endpoint connection tested. Validation should perform a basic API, CLI, database, or endpoint call to verify that the credential is valid, the endpoint is reachable, and the requested permission scope is available. The result should return one of the canonical status states described above, ensuring the Unitt agent only uses connections that are confirmed and operational.