Connectors — call external systems safely
Call external systems from flows with plugin connectors or declarative rest, openapi and mcp instances — pure metadata with reference-based credentials.
Status: Shipped · Audience: App authors (human and AI), integration engineers
TL;DR — A connector packages an external system behind named actions that flows dispatch with the
connector_actionnode. You get one in two ways: a plugin registers it from host code, or — since ADR-0097 — you declare it as pure metadata: aconnectors:entry naming aprovider(rest,openapi, ormcp) is materialized into a live connector at boot, no plugin code required. Credentials are references (credentialRef), never secrets inlined in metadata. This page is the authoring guide for that declarative path — what to write, how auth works, and how it fails.
A connector is a transport mechanism: it knows how to reach one external
system and exposes that system as a set of dispatchable actions. The runtime
keeps a connector registry — GET /api/v1/automation/connectors lists it,
the Studio flow palette browses it, and a flow's
connector_action node dispatches against
it. Connectors are not messaging channels (ADR-0022): "send a Slack message"
is a connector action; routing, templating, and user notification preferences
live in the messaging layer.
The three shapes of a connectors: entry
| Shape | Behavior comes from | When to use |
|---|---|---|
| Plugin-registered connector | Host code: a plugin calls engine.registerConnector(def, handlers) (brand connectors like Slack, or the executors' hand-wired instance options) | The integration needs custom logic, or ships as an installable plugin |
| Provider-bound instance (ADR-0097) | An installed generic executor (rest / openapi / mcp) materializes the entry at boot | The upstream is an HTTP API, an OpenAPI document, or an MCP server — declare it as metadata, write no code |
| Catalog descriptor | Nothing — the entry is inert documentation | Cataloguing a planned or externally-managed integration (below) |
The first shape is code and belongs to plugin development. This guide is about the other two — the entries a tenant (or an AI author) writes into stack metadata.
Declaring a provider-bound instance
A declarative entry becomes a live connector the moment it names a provider:
import { defineConnector } from '@objectstack/spec/integration';
export const BillingApiConnector = defineConnector({
name: 'billing_api',
label: 'Billing API',
type: 'api',
provider: 'rest',
providerConfig: {
baseUrl: 'https://billing.example.com',
},
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' },
});Wire it into the stack alongside your other metadata:
// objectstack.config.ts
export default defineStack({
// ...
connectors: [BillingApiConnector],
});At boot, the automation service resolves each provider-bound entry:
- Look up the provider factory registered under
entry.provider. The three generic executors —@objectstack/connector-rest,@objectstack/connector-openapi,@objectstack/connector-mcp— each contribute one. A scaffolded project (npm create objectstack) lists none: install the provider's package and add its executor toplugins:when the app first declares a connector, beside theautomationcapability that performs the materialization. A plugin is code, so an app that lists one installs only as a managed package, never as an editable (unmanaged) copy. - The factory validates
providerConfigand the automation service resolvesauth.credentialRefto its secret (see WhatcredentialRefresolves through). A reference that is not set yet does not stop the boot: that one instance registers degraded until an administrator sets it. - The result is registered on the connector registry — indistinguishable
from a hand-written connector. Its actions are derived from the
upstream (the OpenAPI document's operations, the MCP server's
tools/list, the REST executor's genericrequest), never authored.
Three authoring rules are enforced when the stack is validated:
providerConfigandauthrequireprovider— on an entry without one they are meaningless materialization inputs and are rejected.- A provider-bound instance must not inline secrets via
authentication(the runtime auth shape) — see Authentication. - A provider-bound instance must not author
actionsortriggers— the provider derives actions from the upstream at boot; authoring both the instance and its actions would let them drift apart (ADR-0097 §5).
Provider config contracts
providerConfig is deliberately not validated by the stack schema — each
provider factory validates its own config at boot (re-modelling an OpenAPI
document or an MCP transport inside the stack schema is exactly what ADR-0023
rejected). A wrong or missing key is therefore not flagged by os validate;
it surfaces as a hard boot error naming the connector. Check the contracts
below against what you wrote.
provider: 'rest' — a generic HTTP client
Config: baseUrl (required, e.g. https://api.example.com) and
defaultHeaders (optional string→string map merged into every request;
request-level headers win).
Materializes a single request action accepting
{ method?, path?, headers?, query?, body? } — the flow supplies the path and
payload per call. Use it when the upstream is "just HTTP" and you don't have a
spec document.
Do not put a credential in headers or defaultHeaders: both are stored in metadata and served with it. Declare it as auth.credentialRef instead — the resolved auth is applied to every request — as the Authorization header, or for api-key as headerName (default X-API-Key) or the paramName query parameter.
provider: 'openapi' — one action per operation
Config: spec (required), baseUrl (optional — overrides the
document's servers[0].url) and include (optional operation allowlist —
only the listed operations become actions). The spec takes any of three forms:
- an inline OpenAPI 3.x document object — no I/O at boot, the most deterministic form;
- an
http(s)URL, fetched at materialization; - a package-relative file path like
'./specs/billing-openapi.json', resolved against the directory containingobjectstack.config.tsand confined to it — absolute and..-escaping paths are rejected.os buildreads the file and writes its JSON intodist/objectstack.jsonin place of the path, so an artifact installed into another runtime carries the document; a path that names no file, or no JSON object, fails the build.
import { defineConnector } from '@objectstack/spec/integration';
export const CrmApiConnector = defineConnector({
name: 'crm_api',
label: 'CRM API',
type: 'api',
provider: 'openapi',
providerConfig: {
spec: './specs/crm-openapi.json',
},
auth: { type: 'api-key', credentialRef: 'CRM_API_KEY', headerName: 'X-API-Key' },
});Each operation becomes an action keyed by its operationId (or a
method_path slug when the document omits one) — so getInvoice in the
document is actionId: 'getInvoice' in your flow.
Each path, query and header parameter is sent by the style and explode its
Parameter Object declares, or by the OpenAPI 3.x default for its location
(form for query, simple for path and header). An object or array input is
encoded the way the document asks — Stripe's created: { gte: 1700000000 }
(deepObject) goes out as created[gte]=1700000000, and its
expand: ['data.customer'] as expand[0]=data.customer (deepObject applied
to an array: each index in its own brackets). A parameter whose style OpenAPI
3.x does not define for its location fails the boot naming the operation and
parameter; leave the operation out of include to bring the rest up.
include takes those same action keys and has the same allowlist meaning as
the mcp provider's include: list the operations the instance should expose
and every other operation stays out — the way to bring up a large API (hundreds
or thousands of operations) as the handful of actions your flows call. An
operation without an operationId is named by its generated method_path key
(delete /customers/{id} → delete_customers_id); one that has an
operationId is named only by it. An entry the document does not carry — a
typo, or an operation the upstream renamed or removed — fails the boot with an
error naming the entry and listing the document's keys; it is never ignored.
providerConfig: {
spec: './specs/crm-openapi.json',
include: ['listCustomers', 'getCustomer', 'delete_customers_id'],
},The document must be OpenAPI 3.x. A Swagger 2.0 document — or one with no
openapi version field — is refused at boot with an error naming the inline
document, URL or file it came from: convert it to OpenAPI 3.x offline and point
spec at the converted document. The runtime never converts.
The ObjectStack repository carries that offline step as a script (it is not
shipped in the npm package): normalize-openapi reads a file or URL, JSON or
YAML, converts Swagger 2.0 to OpenAPI 3.0, bundles and inlines every $ref,
makes servers[0].url absolute, writes one JSON document and prints its
sha256 — and, given allow-patterns, the include list for the operations they
match.
pnpm --filter @objectstack/connector-openapi normalize-openapi \
--in https://example.com/openapi.yaml --out ./specs/crm-openapi.json \
--include-pattern '^GET /v1/customers' --trimWith --trim the document it writes holds only the operations the
patterns match: every other operation, every path item left with none, and
webhooks are dropped before inlining, so nothing reachable only from a
dropped operation is written, and the printed sha256 is the hash of those
trimmed bytes. Package that output — a large vendor document shrinks to the
operations the app calls (Stripe's 612 operations, 63 MB at the default
depth, become about 1.9 MB for six). Without --trim the whole document is
written and the patterns only compute include, so include can be widened
later by editing config alone; with it, widening means re-running the script.
--trim without an --include-pattern is refused.
Inlining is bounded: a recursive schema, or one more than --max-depth
(default 2) named schemas deep, becomes a typed stub whose description names
the reference it replaced. A Swagger 2.0 operation whose empty consumes list
would drop its request body is refused until --empty-consumes <media type>
says which media type it accepts.
provider: 'mcp' — one action per tool
Config: transport (required), include (optional tool-name
allowlist — only the listed tools become actions) and toolsSnapshot
(optional per-tool pin, below):
{ kind: 'http', url, headers? }— a remote MCP server over streamable HTTP. Resolvedauthis folded into the request headers; a grant-bearingauth(oauth2,app-credential) is asked for on every request instead (see Grant-bearing kinds below).{ kind: 'stdio', command, args?, env?, credentialEnv? }— a local child process, policy-gated (below). Resolvedauthis handed to the server in its environment, under the variablecredentialEnvnames (see A stdio server's credential below).
import { defineConnector } from '@objectstack/spec/integration';
export const SearchToolsConnector = defineConnector({
name: 'search_tools',
label: 'Search Tools (MCP)',
type: 'api',
provider: 'mcp',
providerConfig: {
transport: { kind: 'http', url: 'https://mcp.example.com/mcp' },
include: ['web_search', 'fetch_page'],
},
auth: { type: 'bearer', credentialRef: 'SEARCH_MCP_TOKEN' },
});At materialization the provider connects, calls tools/list, and maps each
tool to an action — the MCP server's tool names are your actionIds. A
paginated tool list is followed through every page (nextCursor), up to 100
pages; a server still paging after that fails discovery instead of yielding a
truncated tool list. A server that is unreachable or failing degrades the
instance, which is retried. A credential the server rejects (HTTP 401 / 403 on
connect, handshake or tools/list) is a configuration fault instead: the
instance is degraded naming the refusal, as described under A credential the
upstream refuses below.
include has the same allowlist meaning as the openapi provider's: list the
tools the instance should expose and every other tool stays out — the way to
keep a destructive tool away from your flows and agents. It must be an array of
tool names; any other shape (a string such as include: 'web_search', an
object) fails the boot before connecting, and never falls back to exposing
every tool. An entry the server's tools/list does not carry — a typo, or a
tool the server renamed or dropped — is never ignored: the refusal names the
entry and lists the server's tools. On an instance that sends no static
credential — no auth, an api-key sent as a query parameter, a stdio
transport, or a grant-bearing oauth2 / app-credential instance, whose token
is borrowed per request — it fails the boot. When the instance sends a static
auth credential (bearer, basic, or an api-key header), the entry may
instead be a tool the server hides from that credential: some servers list
only the tools a credential is allowed to use (GitHub's hides each tool a
classic token's scopes do not cover), and the answer does not say what it hid.
That instance is degraded as a credential the upstream refuses (below), never
failing the boot, and its reason names both causes: a credential without the
scopes those tools need, or a declaration naming a tool the server does not
have. Leave include out to expose every tool.
Pinning tools: toolsSnapshot
include decides which tools an instance exposes; it cannot tell you when
the server rewrites one of them — a new description that steers an agent, or
an inputSchema that asks for more than it did. toolsSnapshot pins each tool
you depend on: a record of tool name → the sha256 of that tool's definition.
It is keyed by tool name, like include, and the two compose.
import { defineConnector } from '@objectstack/spec/integration';
export const PinnedSearchConnector = defineConnector({
name: 'pinned_search',
label: 'Pinned Search (MCP)',
type: 'api',
provider: 'mcp',
providerConfig: {
transport: { kind: 'http', url: 'https://mcp.example.com/mcp' },
include: ['web_search', 'fetch_page'],
toolsSnapshot: {
web_search: '08171ae4ba3e1cc962cad9723c755a62c0785d8ecc241a66f08864184366a990',
fetch_page: 'e8478992ffab43667be21a009ae297e3b4e36c7e9b2d3eb26b2ce307fef9cc78',
},
},
});A tool's digest is the sha256, in lowercase hex, of the UTF-8 canonical
JSON of { name, description, inputSchema } taken from its tools/list
entry; a member the server does not send is left out (it is not hashed as
null), and no other member (outputSchema, annotations) is hashed.
Canonical JSON is: object members sorted by key in UTF-16 code-unit order
(JavaScript's default string sort), at every depth; array elements in their
order; strings, numbers, booleans and null written exactly as
JSON.stringify writes them; no whitespace. For values read from JSON that is
the RFC 8785 (JCS) form, so any JCS implementation reproduces it. In code,
computeMcpToolsSnapshot(tools) from @objectstack/connector-mcp builds the
record from a tool list with the same function the check uses.
On every materialization each pinned tool is hashed and compared on its own:
- Every pinned tool served with its pinned definition — the instance materializes as usual.
- A pinned tool served with a different description or
inputSchema, or no longer served at all — the instance registers degraded and exposes none of its tools. Its reason names each such tool, with the digest the server now serves, and the logs say the pin did not match (the provider throwsCONNECTOR_UPSTREAM_CHANGED, not the unreachable-server marker). The instance is re-checked on the retry backoff, so a server that serves the pinned definitions again recovers it on its own; to accept the change, review it and set the pin to the served digest (the edit re-materializes the instance at once). This holds for a pinned toolincludealso lists: once pinned, a tool the server stops serving is reported by the pin, not as anincludetypo. When the instance's own credential reached the server (itsauthover http), a pinned tool the server does not list may be one hidden from that credential, so it is degraded as a credential the upstream refuses instead, naming both causes — a served tool that hashes differently is still reported by the pin. - A tool the pin does not name is not checked. Pin every tool you depend on,
and keep tools the server adds out with
include.
A toolsSnapshot that is not a record of tool name → 64 lowercase hex
characters fails the boot before connecting, and so does a pinned tool that
include leaves out — the instance never exposes it, so its pin would never be
checked.
A stdio server's credential
A stdio MCP server reads its credential from an environment variable, and the
value stays out of metadata the way an http server's does: declare auth with
a credentialRef, and name the variable in transport.credentialEnv. The
platform resolves the reference like any instance's (the environment, then a
credential set under Setup → Connector credentials, then the host's resolver)
and the provider hands the resolved secret to the child in that variable — the
token of a bearer, the key of an api-key, the password of a basic (whose
username, not a secret, goes in env if the server reads it).
import { defineConnector } from '@objectstack/spec/integration';
export const RepoToolsConnector = defineConnector({
name: 'repo_tools',
label: 'Repository Tools (MCP, stdio)',
type: 'api',
provider: 'mcp',
providerConfig: {
transport: {
kind: 'stdio',
command: 'repo-mcp-server',
env: { LOG_LEVEL: 'info' },
credentialEnv: 'REPO_MCP_TOKEN',
},
},
auth: { type: 'bearer', credentialRef: 'REPO_MCP_TOKEN' },
});The value is never stored, logged, served on a metadata read (which shows
credentialRef and credentialEnv, two names) or carried in a message; it
exists only in the environment the server is started with. A reference that
resolves to nothing never starts the server: the instance is degraded naming
the reference, and a credential set later starts it. These fail the boot:
a credentialEnv that is not a variable name, one on an http transport,
one with no bearer / api-key / basic auth to place, and one naming a
variable env also sets. A stdio transport that names no credentialEnv
does not apply auth. A literal credential typed into env instead is
reported by the connector-credential-literal advisory, which points here.
Declarative stdio transports are denied by default. Materializing one spawns a local process from metadata — which a runtime Studio publish can introduce — so anyone who can publish metadata could otherwise execute commands on the server. The host opts in per command:
new ConnectorMcpPlugin({ declarativeStdio: ['node'] }) // exact-match allowlistThe boot error you hit without the opt-in spells out this exact fix. The
allowlist is a deliberately coarse boundary — allowlisting a launcher like
npx effectively trusts anything it can run, so list the specific server
binaries you trust. Hand-wired MCP connectors configured in host code are not
subject to this policy (their command is host code), and http transports
need no opt-in.
Authentication
Connector auth answers "how do we authenticate to the external system" — it is unrelated to how users authenticate to ObjectStack. There are two shapes, and which one you write depends on which of the two connector worlds you are in:
Declarative instances: references, never secrets
Stack metadata is authored, versioned, and shipped — a raw token must never
live in it (ADR-0097 §3). The auth field on a provider-bound instance
therefore has no field that can hold a secret. Its secret-bearing variants
carry a credentialRef instead, resolved at materialization:
auth: { type: 'none' } // public upstream
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' }
auth: { type: 'api-key', credentialRef: 'CRM_API_KEY',
headerName: 'X-API-Key' } // or paramName: 'api_key'
auth: { type: 'basic', username: 'svc_objectstack', // username is not a secret
credentialRef: 'ERP_SVC_PASSWORD' } // the password isVariant notes:
api-key— the key travels in a header (headerName, defaultX-API-Key) or a query parameter (paramName); set one or the other.basic— theusernamestays in metadata (it is not a secret); only the password resolves throughcredentialRef.
What credentialRef resolves through
The metadata author names a credential; the administrator who installs the app holds it. The automation service asks three sources, in order, and the first that answers wins:
- An environment variable of the same name on the server
(
BILLING_API_TOKENabove meansprocess.env.BILLING_API_TOKEN). A self-hosted operator keeps this path, and it always wins. - The connector credential store,
sys_connector_credential: one row per reference, its value encrypted at rest by the host's crypto provider and masked on every read. An administrator fills it through the API below, with no access to the server environment, which is the hosted case. - The host's resolver, when it injects one
(
AutomationServicePluginOptions.credentialResolver, such as a vault or KMS client). You author the same entry either way: it still just names a ref.
A reference no source answers for does not fail the boot. An app installs
first and gets its credentials after, so that one instance registers
degraded: it is listed on GET /api/v1/automation/connectors with a reason
that names the reference, and a dispatch to it fails with the same reason.
Setting a credential
In the Console, an administrator sets them in Setup → Integrations →
Connector Credentials. The page lists every reference with its status, the
connectors that name it, and when it last changed. Each writable reference has
a masked input that starts empty, whatever is stored: typing a value and saving
stores it, and leaving the input empty keeps the current one. A reference with
a value stored here also has Clear. One that an environment variable
supplies is read-only, since the variable wins, and a rejected one shows the
upstream's reason. Where the routes below refuse (a multi-organization
environment, or a server without them), the page shows the server's sentence
instead of a list.
Installing an app from the marketplace ends on the same inputs: once the install lands, the credentials its connectors still need are listed, each with Skip for now. A skipped one leaves its connectors degraded until it is set on the Setup page. The step comes after the install, not before it, because the routes below refuse a reference that no installed app declares.
Over the API, three routes, each requiring the manage_metadata capability:
GET /api/v1/automation/connectors/credential-refs
PUT /api/v1/automation/connectors/credential-refs/BILLING_API_TOKEN { "value": "…" }
DELETE /api/v1/automation/connectors/credential-refs/BILLING_API_TOKENGETlists every reference an installed connector names, plus every stored one that nothing names any more. Each entry has astatus(set,missingorrejected), asource(env,object,vaultornull), whether this door can write it, and the instances naming it with their state. A stored one also says when and by whom it was last set (updatedAt,updatedBy) and when it was last seen working (lastVerifiedAt). It never includes a value.PUTstores the value, then reconciles. Every instance naming the reference re-materializes with it without a restart, and the answer is the reference's entry after that. The route refuses, before writing anything: a reference no installed connector declares (404), one an environment variable already supplies (409, because the variable wins and a stored value would never be read), an empty value, and a value starting withsecret:(400: the store would read it as a handle to another stored secret). With no crypto provider it answers503, since a credential is only ever stored encrypted. Writes on one server run one at a time, each with its reconcile, so the instances always end on the value the store ends on.DELETEremoves the stored value. The instances naming the reference are torn down and registered degraded again.
Installing a package reports the same facts for it: the install-local answer
(POST /api/v1/marketplace/install-local, which os package install calls)
lists the credentialRefs the package's connectors name, each with its status,
plus a credentialNote naming the ones still to set.
A credential the upstream refuses (HTTP 401 / 403) degrades the
instance, with a reason quoting the upstream's message, never the value. An
mcp instance finds this out when it connects, and treats a server that
accepts the credential but does not list a tool its include names the same
way. A rest or openapi instance
finds out on the first call answering 401 / 403; that call returns its
answer as usual, and the instance is degraded after it. What happens next
depends on where the value came from:
- A value stored here is marked
rejected, and its instance is not retried until the credential is set again, its declaration changes, or the server restarts. The mark outlives a restart: it clears only when the value is set again or anmcphandshake that carries it succeeds. Arest/openapicall answered2xxdoes not clear it, because the endpoint may not check the credential at all. - A value from an environment variable or the host's resolver can change
where this door cannot see it (a rotation, or a
403rate limit that lifts), so its instance is retried on the same 5s→5min backoff as an unreachable upstream. The listing reports itrejecteduntil anmcphandshake proves it or the server restarts, even while the instance is serving again.
Credentials are environment-level: one value per reference for the whole
environment, read by whichever instance names it. On a multi-organization
environment (the group or isolated tenancy posture) the store is not used
at all. The three routes refuse with a message naming the posture, and a
reference resolves from the environment variable or the host's resolver only,
so a row stored before the posture changed is not read.
The same resolver serves an api flow's start-node config.secretRef, the
name of its inbound hook secret. That one goes through the injected resolver
alone (environment variables by default) and is read at every post rather than
at boot, so a name with no value refuses each post with 503
(Flows).
Inlining a secret is rejected when the stack is validated. Writing the runtime shape on a provider-bound instance —
// ✗ rejected at authoring/publish:
// "must not inline secrets via `authentication`; reference credentials
// with `auth: { type, credentialRef }` instead (ADR-0097 §3)."
authentication: { type: 'bearer', token: 'sk_live_9f…' },
// ✓ a reference, resolved at materialization (unset, it degrades the instance):
auth: { type: 'bearer', credentialRef: 'BILLING_API_TOKEN' },— fails validation, and auth: { type: 'bearer', token: … } is not even a
legal shape (the declarative union has no token field to put a secret in).
Grant-bearing kinds: oauth2 and app-credential
Some upstreams take no static credential: the token is obtained from a token
endpoint and refreshed as it expires. Two more auth kinds declare that, in
the open tier (ADR-0143). They are grant-bearing: the metadata carries the
endpoints, the client id and a credentialRef for the client or app secret,
never a token. Access and refresh tokens are runtime state and have no key here.
// OAuth 2.0 — a user grants access once (`authorization_code`, PKCE S256 always on):
auth: {
type: 'oauth2',
grant: 'authorization_code',
authorizationUrl: 'https://vendor.example.com/oauth/authorize',
tokenUrl: 'https://vendor.example.com/oauth/token',
scopes: ['crm.read'],
clientId: 'objectstack-prod',
credentialRef: 'VENDOR_CLIENT_SECRET', // omit for a public client
}
// OAuth 2.0 — server to server (`client_credentials`, a confidential client):
auth: {
type: 'oauth2',
grant: 'client_credentials',
tokenUrl: 'https://vendor.example.com/oauth/token',
resource: 'https://api.vendor.example.com',
clientId: 'objectstack-prod',
credentialRef: 'VENDOR_CLIENT_SECRET', // required for this grant
}
// A vendor app credential (Feishu, DingTalk, WeCom): app id + app secret → tenant token
auth: { type: 'app-credential', vendor: 'feishu', appId: 'cli_a1b2', credentialRef: 'FEISHU_APP_SECRET' }What the publish door checks, each refusal located at its key under auth:
oauth2needstokenUrlandclientId, plusauthorizationUrlonauthorization_code. The one exception isprovider: 'mcp'over anhttptransport, which may omit the endpoints and the client id: the MCP authorization flow discovers the server's metadata and can register the client. Anauthorization_codeinstance may instead declareclientSource: 'installer'and name noclientIdand nocredentialRef: the administrator of each deployment registers their own client with the vendor and enters it when they connect (below); aclientIdbeside it is refused.client_credentialshas no authorization step, soauthorizationUrlis refused there, and it requirescredentialRef. AcredentialRefwithout itsclientIdis refused. An inlineclientSecret,refreshTokenoraccessTokenis refused by name, pointing atcredentialRef. There is no PKCE switch.app-credentialtakesvendor(feishu,dingtalkorwecom),appIdand a requiredcredentialRef. An inlineappSecretis refused by name.
How the server serves them. Both kinds are served through a
credential handle the provider asks on every request. The built-in rest,
openapi and mcp providers ask it; a provider says it does by registering with
registerConnectorProvider(…, { credentialHandle: true }). For an openapi
instance the document's security decides only where the token is not
sent: an operation whose effective security is [] is anonymous and never
carries it, and a header or query parameter an apiKey scheme names is the
platform's to fill, so it is left out of the action's input schema, as
Authorization is.
An mcp instance carries a grant-bearing credential only over an http
transport (a stdio server is handed a static credential once, at spawn, in
transport.credentialEnv; a handle on a stdio transport, or beside a static
credential, fails the boot). Every
HTTP request of its MCP session asks the handle. Each organization a dispatch
runs for opens its own session with its own token, so organizations never
share one. The tools are listed at materialization, outside any run, so the
listing names no organization: on an authorization_code instance it uses
the connection connected earliest (connected_at, ties by organization
id), so an instance several organizations connected still lists. When that
connection is revoked, refused or connected again, the instance materializes
again and lists with the next one. A dispatch whose run names no organization
is answered as below: from the only connection, refused when there are
several.
An app-credential instance runs its vendor's exchange from the appId
and the app secret its credentialRef names. The exchange is fixed per
vendor, and nothing about it is authored:
vendor | Token request | Where the token rides on a call |
|---|---|---|
feishu | POST https://accounts.feishu.cn/oauth/v3/token (client_credentials) | Authorization: Bearer |
dingtalk | POST https://api.dingtalk.com/v1.0/oauth2/accessToken | header x-acs-dingtalk-access-token |
wecom | GET https://qyapi.weixin.qq.com/cgi-bin/gettoken | query parameter access_token |
The token belongs to the app, so a run's organization selects nothing, and
there is nothing to connect. It is kept in memory only, never stored (the app
secret re-derives it at any time), and obtained afresh when it is within 30
seconds of its expiry, or once when the upstream answers 401. Concurrent
requests share one exchange. WeCom can invalidate a token before it expires
and says so inside an ordinary answer (errcode 40014 or 42001) rather
than with a 401: such an answer obtains the token afresh once and repeats
the call once, and a second such answer fails the call. No exchange follows a
redirect. An exchange that gets no answer, a 429 or a 5xx fails the
dispatch CONNECTOR_UPSTREAM_UNAVAILABLE, retried on the existing backoff; a
vendor that refuses the app id or secret fails it with 503, naming the
instance and at most the vendor's error code, never the vendor's text.
An oauth2 instance's access token is
obtained from tokenUrl (the client authenticating with HTTP Basic, or by
client_id alone as a public client), cached in memory only, refreshed when
it is within 30 seconds of its expiry, and refreshed once more, with one
retry, when the upstream answers 401. Concurrent requests share one token
request, and with a cluster service a refresh runs under the cluster lock, so
a rotating refresh token is never spent twice.
-
client_credentialsneeds nothing more: the client secret itscredentialRefnames re-derives the token at any time. -
authorization_codeneeds an administrator to connect it, once per organization. Until then the instance is degraded "not connected" (never a failed boot). The connect is three calls, each needing the organization-scopedmanage_connector_connectionscapability. Platform administrators and organization administrators hold it by default, so an organization's owners and admins can connect its vendors from the start; grant it to anyone else through a permission set. Connecting and revoking is a human administrator's act, taken from a signed-in session: an agent acting for them (an OAuth client) or an API key is refused by name, whatever it holds.GET /api/v1/automation/connectors/:name/connection → { status, …, redirectUri } POST /api/v1/automation/connectors/:name/connection → { authorizationUrl, expiresAt } GET /api/v1/automation/connectors/oauth/callback?code=…&state=… (the vendor redirects here) DELETE /api/v1/automation/connectors/:name/connection → revokeAn instance declaring
clientSource: 'installer'takes its client in the connect's body,{ "clientId": "…", "clientSecret": "…" }(omitclientSecretfor a public client). Register that client with the vendor first, with the redirect URI<origin>/api/v1/automation/connectors/oauth/callback: the status read answers that exact URI asredirectUribefore any client exists. That is the one place a client, the Console included, reads it from, never the browser's own origin (wrong behind a proxy, or whenOS_AUTH_URL/OS_BASE_URLname another origin). The authorization request, the code exchange and every refresh of that organization's connection then go out as that client. A reconnect keeps the stored client unless it brings a new one: a connect that names no client reuses the one the organization's connection keeps (the secret is never read back, so it need not be entered again), and one that names a client replaces it. The connection keeps it encrypted; the status read showsclient: { source: 'installer', clientId, hasSecret }, never the secret. A first connect of such an instance without a client (or one after a revoke, which removes the kept client), a client offered to any other instance, and any other body key are refused400 VALIDATION_ERROR.In the Console, Setup → Integrations → Connector Connections drives these calls; the entry is shown to holders of
manage_connector_connections. It lists eachauthorization_codeinstance with the organization's status, the reason the server recorded and, for adegradedinstance, the server's reason beside the connection that caused it. Connect and Reconnect open the vendor's sign-in in its own window, detached from the page, and the page shows the new status once the callback has stored it; Disconnect revokes after a confirmation.GET …/:name/connectionanswers the organization's status (not_connected,connected,reconnect_required), never a token, and, whatever the status,redirectUri: the deployment's redirect URI to register with the vendor. It is absent when the deployment has no base to derive it from (the read still answers; a connect is then refused503), never guessed from the request. Thestateand the PKCE verifier are bound to the user and organization that began the connect and are used once; a callback from anyone else is refused before its code is exchanged. While the connect waits (ten minutes at most) it is held in the cluster KV, or in process on a single node, sealed under a key derived from thestateitself, which the server never stores: the KV holds only the state's digest and an AES-256-GCM envelope, so a party that can read the KV learns no verifier, user or organization, and a value edited or moved there opens as nothing and its code is never exchanged. Write access to the cluster KV stays inside the platform's trust boundary, as it is for the cluster lock: such a writer can still delete a waiting connect. On anmcpinstance overhttpthat leaves its endpoints or its client to discovery, the connect runs the MCP authorization flow: the server reads the MCP server's protected-resource metadata (RFC 9728), then its authorization server's metadata (RFC 8414, or OpenID Connect discovery). That metadata'sissuermust be the one the MCP server named, andS256must be listed. A declaredclientIdis used as is; otherwise a public client is registered (RFC 7591) for the deployment's redirect URI, and an authorization server with no registration endpoint is refused, naming theclientIdto declare. Every authorization and token request carries the MCP server's resource indicator (RFC 8707), and a callback that names another issuer is refused before its code is exchanged (RFC 9207). Every URL on the way must behttps://(plainhttp://only to a loopback host), and no request follows a redirect. An MCP or authorization server that does not answer (or answers429/5xx) refuses the connect with503; metadata that is missing or fails a check above, with400. The discovered endpoints and client, including any client secret the registration issued, are kept encrypted in the connection'sregistered_client; refreshes use them, and a reconnect reuses them instead of registering again. The redirect URI is the deployment's (OS_BASE_URLorOS_AUTH_URLplus/api/v1/automation/connectors/oauth/callback, or the automation plugin'sconnectorOAuthRedirectUri), never the request's; register that URI with the vendor. The refresh token is kept encrypted insys_connector_connection, one row per organization and instance, an instance being its package and name (one per organization for an instance the environment authored or a plugin registers); it is not a sign-in account, and signing in never touches it. A callback completes the instance its connect was begun for, never the name read again, and the bare connect door refuses with409a name two packages hold rather than pick one: connect each package's instance at its namespace address,/api/v1/automation/connectors/NS/NAME/connection(see Two packages, one connector name). A run dispatches with its own organization's connection; a run with no organization uses the instance's only connection, and is refused when there are several. When the grant stops working, the connection is marked reconnect required and the instance degraded until an administrator connects it again. That happens when the vendor refuses the grant on refresh (invalid_grant), when the connection keeps nothing to renew an access token it has to renew with (the vendor issued no refresh token, or no client is kept to refresh with), or when the upstream refuses the connection's token while anmcpinstance discovers its tools. The connection'sstatusReasonsays which. A refresh, and the mark "reconnect required", are each written only over the revision they read, in one conditional write, so a stale one never overwrites a newer connect on any replica. A revoke deletes the stored connection only: the server does not revoke the refresh token at the vendor (RFC 7009), because no revocation endpoint is known for the instance — the auth declares none, and the MCP authorization flow does not read one. The refresh token stays valid at the vendor until it expires or is revoked in the vendor's console; revoke it there too when the disconnect is a response to a leak.
What is not served yet is held degraded with a reason that names it, and
never called without its credential: an oauth2 or app-credential
instance on a provider that does not ask the credential handle (a plugin's
provider registered without { credentialHandle: true }), an oauth2
instance without its endpoints or client that the MCP authorization flow
cannot discover them for (only an authorization_code instance on
provider: 'mcp' over an http transport does), an mcp instance left to
discovery whose transport url is not https://, and an oauth2
instance whose tokenUrl or authorizationUrl is not https:// (plain
http:// is accepted only to localhost, a 127.0.0.0/8 address or
[::1] — not a *.localhost name, which the system resolver sends to DNS —
so the client secret and the refresh token never cross a network in the
clear; a token endpoint that answers with a redirect is refused rather than
followed). A datasource
that borrows from a grant-bearing instance (external.connector) is refused
with 422. Until then, declare a static kind (bearer, api-key or basic)
to dispatch now; don't emulate a grant by putting a short-lived access token
behind a bearer ref.
Request signing: signed
Some upstreams take no token at all: every request carries a signature over its
own method, path, query, headers and body, computed with a key the caller never
sends. The signed kind declares that (ADR-0143 D2.3). The metadata names the
scheme and the public key id; the signing key itself is a
credentialRef, resolved through the same chain as every other kind. A scheme
whose vendor signs its responses also names the vendor's public key, as a
second reference.
// Alibaba Cloud OpenAPI, V3 signature (ACS3-HMAC-SHA256):
auth: {
type: 'signed',
scheme: 'aliyun-acs3-hmac-sha256',
keyId: 'YourAccessKeyId', // the AccessKey ID: public, stays in metadata
credentialRef: 'ALIYUN_ACCESS_KEY_SECRET',
}
// Tencent Cloud API 3.0, signature v3 (TC3-HMAC-SHA256):
auth: {
type: 'signed',
scheme: 'tencentcloud-tc3-hmac-sha256',
keyId: 'YourSecretId', // the SecretId: public, stays in metadata
credentialRef: 'TENCENT_SECRET_KEY',
}
// Alipay OpenAPI v3 (ALIPAY-SHA256withRSA), responses verified:
auth: {
type: 'signed',
scheme: 'alipay-v3',
keyId: '2021000000000000', // the app id: public, stays in metadata
credentialRef: 'ALIPAY_APP_PRIVATE_KEY', // the application private key (RSA)
vendorPublicKeyRef: 'ALIPAY_PUBLIC_KEY', // the Alipay public key responses are verified with
}Both of an alipay-v3 instance's references are listed against it by the
credential door, and setting or replacing either one re-materializes it. The
keys are accepted as Alipay's console issues them (the bare base64 body) or as
PEM.
What the platform does with it:
- Every request is signed, each attempt fresh. A retry is signed again with a new nonce and date, so a scheme that refuses a replayed nonce or a stale timestamp accepts it.
- The key never reaches the provider. The automation service binds the
resolved key to the scheme's signer at materialization and hands the
provider the signer only. A datasource cannot borrow a
signedinstance (external.connectoris refused with422): a driver cannot sign per request. - Schemes that sign their responses are verified before a result is returned; a response that does not verify fails the dispatch, and its body never reaches the flow.
aliyun-acs3-hmac-sha256signshost,content-typeand everyx-acs-*header, and setsx-acs-date,x-acs-signature-nonce,x-acs-content-sha256andAuthorization. The API's own action and version are yours to send, asx-acs-action/x-acs-versionindefaultHeaders(rest) or in each call's headers.tencentcloud-tc3-hmac-sha256signscontent-typeandhost, and setsX-TC-TimestampandAuthorization. The service in the signature's scope is the first label of the endpoint host (cvm.tencentcloudapi.com, or a regionalcvm.ap-guangzhou.tencentcloudapi.com, iscvm), so pointbaseUrlat the product's own endpoint.X-TC-Action,X-TC-VersionandX-TC-Regionare yours to send and are not signed. A request without a content type is sent withContent-Type: application/x-www-form-urlencoded, the type it is signed with.alipay-v3signs the method, the path and query as sent and the body, with a fresh nonce and millisecond timestamp, and setsAuthorization: ALIPAY-SHA256withRSA app_id=…,nonce=…,timestamp=…,sign=…. Every response below status 400 must carry a validalipay-signature(an empty body too), checked against the keyvendorPublicKeyRefnames; an error response is verified when it is signed, and an unsigned one fails as the error it is. Public-key mode only: Alipay's certificate mode is not supported.
What the publish door refuses:
- An unknown
scheme, atauth.scheme, naming the scheme it got and the ones this platform ships. A scheme joins the list only together with its signer and its test vectors, so a scheme the server cannot run is never accepted. - An inline key:
secret,privateKey,secretKeyoraccessKeySecretis refused by name, pointing atcredentialRef(onalipay-v3,appPrivateKeytoo, andalipayPublicKeypoints atvendorPublicKeyRef). The vendors' words for the key id (accessKeyId,secretId,appId) are answered withkeyId. An authoredsignatureis refused too: it is computed for every request. provider: 'mcp', atauth.type: an MCP server is not signed per request. Declareprovider: 'rest'orprovider: 'openapi'.
signed and a static credential do not combine: a request is authenticated
one way. An openapi instance's remote spec URL is fetched unsigned, as
before; only the API calls are signed. A third-party provider factory serves a
signed instance only when it says it applies the signer
(requestSignerApplied on its materialization); one that does not is refused at
boot rather than allowed to call the upstream unsigned.
The runtime shape: authentication
The authentication field is the runtime auth config, with four static
variants (none, bearer, api-key, basic). It carries the resolved
secret inline ({ type: 'bearer', token }), because it is supplied
by host code (a plugin calling engine.registerConnector, or the
executors' hand-wired instance options reading process.env). That is a
different trust anchor than metadata: code review guards what enters it, and
it is never serialized into a versioned artifact. On declarative entries,
leave authentication alone — provider-bound instances must use auth, and
catalog descriptors documenting a planned integration must still never carry a
live secret value.
The runtime shape's oauth2 variant was removed in @objectstack/spec 18
(ADR-0143 D7): it held a client secret and a refresh token inline and nothing
ran its lifecycle. authentication: { type: 'oauth2' } is refused with that
prescription; declare the grant on an instance's auth instead, as above.
Dispatching from a flow
A materialized instance is dispatched exactly like any other connector — by
name and action key:
{
id: 'ping',
type: 'connector_action',
label: 'GET /api/v1/health',
connectorConfig: {
connectorId: 'billing_api', // the connector's `name`
actionId: 'request', // rest: 'request' · openapi: operationId · mcp: tool name
input: { method: 'GET', path: '/api/v1/health' },
},
},See Flows for the node reference and how outputs flow into downstream nodes.
Two packages, one connector name
Two packages that declare different namespaces may each declare a
connector of the same name. Each is its own instance, held by its package
and name: each is materialized, connected, credentialed and listed on its own
(GET /api/v1/automation/connectors lists both, each descriptor carrying its
packageId). Two packages of one namespace still may not, nor a package
that declares no namespace beside another holder: the install is refused,
naming both, as before. A deployment that already holds such a pair (code
packages a boot only warns about) materializes each instance under its
package, but no HTTP address tells them apart: the namespace door answers
409 for both. Give one of them its own namespace.
A bare name is resolved for whoever names it, and never picked between two holders:
| Who names the connector | Which instance it means |
|---|---|
A flow's connector_action (connectorId) | The flow's own package's instance, else the one holder in the package's declared dependencies; refused, naming every candidate, when its reach holds two or holds it only outside |
| A flow the environment authored | The environment's own instance, else the one package holder; refused, naming both, when two packages hold it |
A connector pull (mapping.connectorSource.connector) | Resolved as a flow is, from the package that holds the mapping (an environment mapping: as the environment's flow). A refused name fails the pull 409 (connector_name_refused); a name that resolves to a package with no live instance is connector_not_registered, never another package's instance |
The connection door, /api/v1/automation/connectors/NAME/connection | The one holder of the name; 409 naming both when two packages hold it |
The connection door at the namespace address, /api/v1/automation/connectors/NS/NAME/connection | The instance of the package of namespace NS: connect, read and revoke each package's connection there |
GET /api/v1/meta/connector/NAME | 409 naming both when two packages hold it; read each with ?package=ID or /meta/connector/NS/NAME |
Each package's instance has its own connection per organization: connecting one leaves the other's untouched, and revoking one leaves the other serving.
A connector a plugin registers in code is no package's: it is dispatched by
its name as before. A package may still declare a catalog descriptor of that
name (an entry without a provider); the package's flows are then served the
plugin's connector.
A disabled package holds no name for anyone else: its instance is not served to a caller outside the package, even before the next reconcile removes it. A flow of the disabled package itself still reads its own instance. An entry with no package of its own over a name only a disabled package holds is that package's instance, and is not dispatched until the package is enabled again.
Failure modes at a glance
Boot distinguishes configuration faults (your entry is wrong — fail loud, fix the metadata) from operational faults (the upstream is down — degrade, retry):
| You wrote / it happened | What you get |
|---|---|
provider names no installed factory | Hard boot error naming the entry, the provider, and the plugin that supplies it — add the executor to plugins: |
Invalid providerConfig (missing baseUrl / spec / transport, wrong shape) | Hard boot error from the provider factory |
auth is a grant-bearing kind (oauth2, app-credential) on a provider that does not ask the credential handle (a plugin's provider registered without { credentialHandle: true }) | Not fatal: the instance registers degraded, naming the kind, and the upstream is never called without its credential; a datasource borrowing it is refused with 422 |
An authorization_code instance nobody connected, or whose grant stopped working (the vendor refused it on refresh, no refresh token or client to renew an access token with, or the upstream refused its token at MCP tool discovery) | Not fatal: the instance registers degraded, "not connected" or "reconnect required" — connect it (POST …/connectors/:name/connection), and it materializes without a restart |
The token endpoint is unreachable or answers 5xx / 429 | Not fatal: the dispatch fails CONNECTOR_UPSTREAM_UNAVAILABLE and is retried on the existing backoff; the connection stays connected |
auth is signed on a provider that does not say it applies the request signer | Hard boot error naming the instance, the scheme and the provider: its calls would go out unsigned — declare it through rest or openapi |
credentialRef (or a signed instance's vendorPublicKeyRef) resolves to nothing | Not fatal: the instance registers degraded, naming the reference — set it (PUT …/credential-refs/:ref), and it materializes without a restart |
A signed reference resolves to something that is not a key of the scheme's kind (an alipay-v3 key that is not RSA) | Hard boot error naming the instance and which reference cannot sign or verify, never the value |
A response to an alipay-v3 call is unsigned (below status 400) or its signature does not verify | The dispatch fails naming the instance and the status; the response's body is never returned |
The upstream refuses the credential (401 / 403), or an mcp server sent a static credential does not list a tool the instance's include names | Not fatal: the instance registers degraded. A stored credential is marked rejected and waits until it is set again (or a restart); an environment or vault credential is retried on the backoff |
Instance name collides with a plugin-registered connector | Hard boot error — there is no silent precedence between the two worlds |
Two entries of one package share a name | Hard boot error naming the name and the package (a stored entry is logged and skipped): a name is unique within a package |
An entry with no package of its own (one the environment stored, or an unstamped one) shares a name two packages hold | Not materialized, refused naming both holders, since which package's instance it would be cannot be told: a host's own entry fails the boot, a stored or installed one is logged and skipped. Declare it in one of the packages, or under another name |
| stdio transport without host opt-in | Hard boot error with the declarativeStdio fix inline — a security rejection is never retried |
An entry of an installed package (os package install, POST /api/v1/marketplace/install-local) names a package-relative file — an openapi spec path — or needs a location inside its package, as a stdio mcp transport's working directory does | Configuration fault, never resolved against the host's directory: an installed package has no directory on the runtime it was installed into, and the host's is not its own. The instance is not materialized, and the reconcile's error names the entry, its package and the ref. Rebuild the package with a current os build, which carries an openapi spec file into the artifact, or inline the document; reach an MCP server from an installed package over http. Whether an entry is the host's is read from what the install recorded, never from the package's own words: an entry carrying a _packageId other than its own package's is refused at the install, every member of a packages[] bundle is recorded as installed whatever its source says, and an entry naming a package no registration records is refused its ref too. The host's own entries keep reading their files |
A stored entry — one saved in this environment through the metadata door (PUT /api/v1/meta/connector/:name, Studio), environment-wide or in a package created here (POST /api/v1/packages) — names a package-relative file or needs a location inside a package | Configuration fault, never resolved against the host's directory: a stored definition is no package's declaration and has no directory on disk. The instance is not materialized, and the reconcile's error names the entry, its package if it has one, and the ref. This one is never fatal, even at boot: a stored row at rest is logged and skipped, and the platform starts. Carry the document inline in the definition, or name it by an http(s) URL; reach an MCP server from a stored entry over http. Only what the host's own stack declares reads its files: a stored row is never read as the host's, whatever _packageId its body carries |
MCP server unreachable / tools/list fails; remote spec URL unreachable or transiently failing (408/429/5xx) | Not fatal: the instance registers degraded (visible on GET /api/v1/automation/connectors with the reason), dispatches fail with that reason, and the platform retries on a 5s→5min backoff — recovery is automatic |
An mcp instance's toolsSnapshot does not match what the server serves (a pinned tool's description or inputSchema changed; or a pinned tool is no longer listed, on an instance whose credential did not reach the server) | Not fatal: the instance registers degraded with no actions, its reason naming each tool and the digest it now serves, and the logs say "serves a tool definition that differs from its toolsSnapshot" (CONNECTOR_UPSTREAM_CHANGED); it is re-checked on the same backoff and recovers once the server serves the pinned definitions again — or set the pin to the reviewed digest. A pinned tool no longer listed on an instance whose credential did reach the server (its auth over http) takes the credential row above instead: a server may hide tools from a credential, so the reason names both causes (fix the credential and set it again, or update the pin), a stored credential is marked rejected, and no retry runs against the same value |
A retry of a degraded instance reaches the upstream and meets a configuration fault (an include naming a tool or operation the upstream does not offer; on an mcp instance that sends a static credential, the credential row above applies instead) | Not fatal: the instance stays degraded, now with the configuration reason, and is not retried — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it |
| Wrong spec URL (other 4xx) or unparseable document | Configuration fault — hard boot error |
An openapi operation's parameter declares a style OpenAPI 3.x does not define for its location (deepObject on a path parameter, form on a header) | Configuration fault — hard boot error naming the operation and the parameter; correct the document or leave the operation out of include |
A connector_action input value whose shape the parameter's style has no encoding for (an array of objects for form, an object for a content-typed parameter) | The step fails before dispatch naming the parameter, and nothing is sent |
A connector_action input that, once evaluated, breaks the action's inputSchema (a missing required parameter, a wrong type) | The step fails before dispatch with VALIDATION_ERROR, naming each parameter path, and nothing is sent; a fault edge or try_catch can route it. Supply the parameter or send the declared type: text is never converted, so cast it in a CEL envelope (int(), double(), bool()). GET /api/v1/automation/connectors lists the schema; os validate does not judge the input against the inputSchema yet |
A bad entry arrives via runtime reload (a Studio publish, a direct active save through PUT /api/v1/meta/connector/:name, or a delete, made on any replica — peers reconcile on cluster lane 2; or a dev reload) | Logged and skipped, never crashing the live server; a changed instance's old connector keeps serving until its replacement materializes |
A bad entry belongs to a package installed into the runtime (POST /api/v1/marketplace/install-local), at the install or at a restart that registers the package again | Logged and skipped, as on a runtime reload: the boot completes and the package's other instances materialize |
Catalog descriptors: entries without a provider
An entry with no provider never reaches the registry — it is an inert
descriptor for discovery, documentation, or marketplace listing. It may
author actions (as documentation of a planned surface, including I/O JSON
Schemas). Because a declared-with-actions connector that nothing registers is
usually a mistake, boot warns about it — mark a deliberate descriptor with
enabled: false to state the intent and silence the audit:
import { defineConnector } from '@objectstack/spec/integration';
export const ErpCatalogConnector = defineConnector({
name: 'erp_catalog',
label: 'ERP Integration (planned)',
type: 'saas',
description: 'Planned ERP integration — catalogued, not yet dispatchable.',
actions: [
{ key: 'get_invoice', label: 'Get Invoice' },
],
enabled: false, // deliberate catalog-only descriptor: suppresses the boot audit warning
});A descriptor sharing a live connector's name stays legal — it is catalog metadata about that connector. (A provider-bound instance sharing one is the boot error from the table above.)
A complete, runnable example
The showcase app exercises every shape on a real boot —
examples/app-showcase/src/system/connectors/index.ts
declares a rest instance pointing at the server's own health endpoint, an
openapi instance whose spec is a package-relative file, an mcp instance
spawning the in-repo stdio fixture under a declarativeStdio allowlist, and a
catalog descriptor — with flows dispatching the rest and mcp instances
end-to-end. Start from it rather than assembling the shapes from scratch:
pnpm devRelated pages: Flows · Webhook Delivery (the outbound-notification counterpart) · Connect an MCP Client (the opposite direction: exposing this platform to an external MCP client) · Connector schema reference (generated from the schema).
Webhook Delivery
How ObjectStack reliably ships outbound HTTP notifications — from event to receiver — with at-least-once guarantees, signed payloads, and observable retries.
Scheduled Jobs
Run a sandboxed body, a connector pull, or a TypeScript function on a cron, interval, or one-off schedule — and decide when a job is the right tool instead of a schedule-triggered flow.