Skip to main content
Every Prisme.ai connector — Jira, Salesforce, Google Workspace, SharePoint, and the rest of the marketplace — is built from the same architecture: a single Prisme.ai workspace, published as an app, that wraps a third-party API and exposes it through two surfaces at once — DSUL App-mode instructions for Builder workflows and an MCP server for Agent Factory agents. This page explains that shared model so you can reason about how a connector authenticates, authorizes agents, and routes calls — whether you consume one or build your own.
This is a conceptual overview. For the user-facing setup of a specific connector, open its page (e.g. Jira, Google Workspaces). To build a connector, the internal app-mcp-implement skill reproduces this architecture end-to-end.

​
The model in one picture

A connector is never called directly. It is published as an app and installed as an app instance inside a tenant workspace. Both the App-mode instructions and the MCP endpoint then run in that tenant’s app-instance context, so the connector reads the tenant’s own configuration and secrets locally — there is no central shared key and no cross-workspace credential lookup on the hot path.
A connector app instance runs inside the tenant workspace: an Agent Factory agent calls the MCP endpoint, a DSUL automation calls App-mode instructions, both converge on buildAppAuth then registry dispatch, then the external API.
The same workspace serves both callers; only the entry point differs. A DSUL automation calls a named instruction; an agent lets the LLM pick an MCP tool. Both converge on the same authentication and dispatch code.

​
Two consumption surfaces

App mode (DSUL)

Builder automations call named instructions like Jira.searchJira(). The caller chooses the operation; arguments and outputs are plain JSON. Best for deterministic workflows, data pipelines, and scheduled jobs.

MCP mode (agents)

Agent Factory agents connect to the MCP endpoint and discover tools automatically. The LLM selects which tool to call. Best for conversational interfaces and agentic tasks.
Both surfaces are backed by the same operations. Adding an operation to a connector makes it available to Builder automations and to agents simultaneously.

​
Anatomy of a connector

A connector spans two sibling folders, linked one-to-one by name: the DSUL workspace (the runtime logic) and a React configuration app (the setup UI). 
connector/
├── workspaces/<slug>/        ← DSUL: runtime logic
│   ├── index.yml             ← config schema, MCP tool definitions, secrets schema
│   ├── automations/          ← the MCP endpoint, auth, dispatch chain, per-op wrappers
│   ├── imports/              ← MCP Core (initialize / tools/list) + Custom Code registry
│   └── security.yml
└── pages/<slug>/             ← React config app (SPA): auth setup, agent allowlist
The key automations, and what each one does:
ComponentRole
MCP endpointJSON-RPC 2.0 handler. Routes tools/call through auth + dispatch; delegates initialize / tools/list to MCP Core.
validateAgentChecks the calling agent against the per-instance allowlist before any tool runs.
buildAppAuthResolves credentials for the tenant’s configured auth mode and returns an access token + base URL.
Registry (Custom Code)Maps entity + action → operation → {method, path, params}. The single source of truth for the API surface.
Dispatch chainrouteToolCall → toolRestOp → executeApiCall → formatToolOutput, with a shared handleApiError.
Per-operation wrappersThin App-mode automations (Connector.operation:) reached dynamically through the registry — one per API operation.

​
Request lifecycle

When an agent calls a tool, the MCP endpoint runs a fixed pipeline:
Sequence of an MCP tool call: the agent calls tools/call on the MCP endpoint, which validates the agent, resolves credentials via buildAppAuth, dispatches through the registry to the external API, then returns a bounded result to the agent.
1

Identify the agent

Agent Factory injects the agent identity (context_id, agent_id, user_id) into the tool call. validateAgent checks agent_id against the instance allowlist. An unauthorized agent is rejected before anything runs.
2

Resolve credentials

buildAppAuth reads the tenant’s auth configuration and returns an access token and base URL for the request — refreshing per-user OAuth tokens on the fly when needed.
3

Dispatch through the registry

The tool name (an entity) plus its action argument resolve to a concrete {method, path, params} through the registry, and executeApiCall performs the authenticated HTTP call.
4

Format and bound the result

formatToolOutput wraps the response for the caller. Results are size-bounded (arrays capped, long text truncated on a line boundary) so a large payload never overflows the agent’s context window.
The App-mode path is the same minus the agent checks: a DSUL instruction calls buildAppAuth directly, dispatches through the registry, and returns the raw API JSON (no MCP envelope) for the automation to consume.

​
Entity-grouped tools

Connectors do not expose one tool per API endpoint — that would flood an agent with hundreds of near-identical tools. Instead, related endpoints are grouped into a handful of entity tools, each taking an action enum: 
// One entity tool, many actions
{
  "name": "records",
  "arguments": {
    "action": "create",        // list | get | create | update | delete …
    "sobject": "Account",
    "fields": { "Name": "Acme Corp" }
  }
}
This keeps the tool count small and LLM-friendly (typically 6–12 entities per connector) while the registry maps each entity + action pair to the underlying operation. Tool schemas are authored to be strict-provider safe: no dangling $refs, bounded descriptions, and typed array items — so enabling a connector never breaks an agent’s completion.

​
Authentication

A connector supports one or more auth modes, all resolved by buildAppAuth from a single tenant configuration object. A tenant picks the mode that fits its provider setup in the config app.
ModeHow it worksTypical use
API keyStatic key sent in a header or query parameter.Simple APIs, service credentials.
Access tokenCaller supplies a token + base URL directly.Quick setup and testing.
Client credentialsOAuth2 client_credentials grant (service identity).Machine-to-machine access.
JWT / service accountSigned JWT bearer assertion.Google domain-wide delegation, Salesforce Connected App.
OAuth2 per-user (PKCE)Authorization-code + PKCE, one token per end user.User-scoped access in a chat or workflow.
Least privilege. A connector never forces write scopes: it requests exactly what the auth configuration grants. Restricting the credential (a read-only API key, a read-only scope list, or a read-only provider role) makes the connection succeed while write calls return 403. Each connector page documents the concrete read-only lever for its service.

​
Central platform OAuth

For OAuth connectors, tenants should not need to register their own provider OAuth client. A platform maintainer provisions one central OAuth client on the connector’s core workspace, and tenants get a zero-config OAuth mode: one click on Connect, no client ID or secret to paste. Because a connector’s secrets never resolve inside a tenant instance, the central client is exposed as a token service on the core workspace: a public endpoint returns the client ID and scopes (never the secret), and a proxy endpoint performs the token exchange server-side, injecting the central credentials. The tenant keeps the PKCE exchange locally and never sees the secret. A single provider redirect URI (the core callback) is registered once; per-tenant callbacks are carried in the OAuth state and proxied back after the exchange.

​
Agent authorization

Two independent gates decide whether an agent can use a connector — do not confuse them with OAuth scopes:

Capability scope

The MCP capability is declared with Scope context_id,agent_id,user_id. This injects the agent and user identity into every tool call, so the connector knows who is calling — no API key is minted for the agent.

Per-instance allowlist

validateAgent checks the injected agent_id against the instance’s allowlist. Only allowlisted agents run tools. A wildcard (*) sentinel authorizes every agent when a tenant opts into it.
Declaring the capability in a catalog makes the connector discoverable; the allowlist is what authorizes a specific agent. Both are managed from the config app — no hand-editing of platform settings.

​
Configuration app

Each connector ships a React configuration app that a tenant uses to set everything up: choose the auth mode and enter credentials (or click Connect for OAuth), test the connection, select which agents may use the connector, and install the MCP capability onto them. It talks to the platform with the user’s own session, so native RBAC applies. The config app renders in two places from the same bundle: inline inside the tenant’s app-instance editor (the preferred surface), and at a standalone URL surfaced on the instance config. OAuth connectors additionally expose a maintainer view — visible only to the connector’s own workspace admins — for provisioning the central OAuth client and publishing the connector into the org-wide capabilities catalog.

​
Deployment model

A connector moves from source to a usable integration in three steps:
1

Publish the workspace as an app

The DSUL workspace is published to the marketplace under a stable app ID. The published app snapshots the config schema, MCP tool definitions, and the config-app bundle pointer.
2

Install as an app instance

A tenant installs the app into its workspace. Installation provisions the tenant’s secrets and configuration bindings and surfaces the config app.
3

Configure and wire

In the config app the tenant sets auth, tests it, allowlists agents, and installs the MCP capability. The connector is now callable from both DSUL automations and agents.

Browse connectors

The full list of available connectors and how to choose App vs MCP mode.

Agent capabilities

How Agent Factory agents discover and consume MCP tools.

Building custom connectors

Create your own connector for any API.
https://mintcdn.com/prismeai/dzAaoAETtV2DGkv4/images/connectors/jira-next.png?fit=max&auto=format&n=dzAaoAETtV2DGkv4&q=85&s=9e1ce01bb19b6ac2a0b7783ca6c4244b

Jira connector

A concrete tenant-context connector to see the model in practice.