Nexra Gateway and capability graph

One application scope

Open Nexra Connect → Gateway and choose an application. The application's project limits which active connections the Gateway can discover. Workspace membership and operation permissions are enforced on the server. A connection in another project is not a fallback.

The Gateway uses reviewed recipe and built-in connector contracts, plus operation definitions saved on your private REST/OpenAPI connection. These contracts describe implementation. They do not establish the provider account's permissions or prove that a complete workflow has been qualified.

Discover, describe and resolve

Add these tools to a reviewed MCP server version and publish that version before granting them to an external client. Existing credentials do not gain new tools automatically.

A contact, company, account or partner can be a candidate for customer management without being a billable customer. The resolver includes semantic caveats and returns clarification_required when several accounts or operations match. Choose both the connection and operation; Nexra never silently picks the first account.

MCP and REST

MCP clients call the tools on /mcp using the existing OAuth, session and protocol headers. The REST transport uses POST /api/gateway/tools/{toolName} on the same API origin with the same OAuth access token, credential grants, published server policies, rate limits and approvals. It does not require an MCP session header.

{
  "arguments": {
    "query": "customers",
    "mode": "read",
    "limit": 5
  },
  "meta": {}
}

REST returns the same tool result envelope as MCP: content contains a text entry whose text is the JSON result. Errors use HTTP status codes. The console uses its authenticated workspace member, with equivalent project scope, through /api/console/gateway/applications/{applicationId}/tools/{toolName}.

Input conventions

Always inspect the operation before executing it.

Private API approval hashes include path parameters, query fields and body. Changing the resource ID invalidates an approval even if the body is unchanged. Approvals also bind the connection configuration, credential reference, operation contract and deployed backend release. Configuration, credential or backend release changes require a fresh approval. Oversized JSON, non-finite numbers and unsafe property names are rejected before dispatch.

Governed writes and retry safety

Writes require all three conditions: the deployment's NEXRA_MCP_CAPABILITY_WRITES_ENABLED switch, explicit allowedWriteOperations on the connection, and an applicable policy that permits execution or a valid independent approval. The switch applies to Gateway and MCP execution; a release does not turn it on automatically.

The governed gate now covers built-in and private API writes as well as recipe writes, including flow destinations and dead-letter retries. Existing built-in destinations need explicit write permission before they can run. An authorized operator can allow or stop an implemented write using PUT /api/console/connect/connections/{connectionId}/write-operations with {"operationKey":"customers.upsert","enabled":true}. This changes no provider credential or origin. Unknown operations fail closed.

Use a stable idempotency key for each intended write. Successful repeated requests return an evidence reference. An atomic database dispatch claim prevents simultaneous Gateway requests with the same key from sending the write twice. Native flow writes also claim each stable execution-record and destination-step key independently; failed or interrupted provider outcomes cannot automatically dispatch again under that key. A failed or interrupted provider call can have an unknown external outcome: Nexra refuses automatic replay under that key. Reconcile the provider and evidence before considering a new attempt. This does not promise exactly-once execution by an external provider.

When a write returns approval_required, a different authorized workspace member must approve it. Retry with unchanged input and key, setting meta["nexra/approvalRequestId"] to that approval ID. Approvals expire, are bound to the exact action, and are single use.

Workflow plans and qualification

The initial blueprints cover customer/invoice lookup, invoice reconciliation, and lead-to-customer. Call compose_workflow without a key to list them. Select one connection and operation per step, then submit bindings:

{
  "arguments": {
    "workflowKey": "customer_invoice_lookup",
    "bindings": [
      {
        "stepKey": "customers",
        "connectionId": "chosen-company",
        "operationKey": "customers.list"
      },
      {
        "stepKey": "invoices",
        "connectionId": "chosen-accounting",
        "operationKey": "invoices.list"
      }
    ]
  }
}

A bound plan returns a version and fingerprint, required qualification checks, ready_for_mapping, qualification: "not_run" and executionAllowed: false. Composition creates no provider side effect. Complete field mappings, duplicate handling, error recovery and qualification before promoting a reusable workflow. A deterministic fixture run is not a live provider qualification.

Node.js SDK

Download the current runtime and TypeScript declarations from GET /api/gateway/sdk/typescript. Save the returned files with their supplied names, together in your project. The SDK requires Node.js 22 or later and makes no automatic retries.

const { NexraGateway } = require("./nexra-gateway.cjs");
const gateway = new NexraGateway({
  baseUrl: process.env.NEXRA_API_ORIGIN,
  token: () => process.env.NEXRA_ACCESS_TOKEN,
});
const matches = await gateway.search("customers", { mode: "read" });
const description = await gateway.describe({
  connectionId: "chosen-company",
  operationKey: "customers.list",
});

Keep the access token on the server. Provider credentials stay in Nexra's existing secure connection references; do not pass them to the SDK.

Workflow qualification samples

qualify_workflow is the sixth shared MCP/API/SDK tool. Publish it explicitly and grant both connect:read and connect:execute; existing credentials are not automatically expanded. The SDK exposes gateway.qualify(request).

The tool supports customer_invoice_lookup and invoice_reconciliation on sandbox connections only. Supply both explicit bindings, per-step inputs, and a mapping object with leftKey and rightKey. Reconciliation additionally requires invoiceAmount, paymentAmount, invoiceCurrency, paymentCurrency, paymentStatus and settledStatuses. Amount fields must contain integer minor-unit strings, currencies must match as uppercase three-letter codes, and a payment must have an explicitly declared settled status. Multiple records for one reference, unmatched or missing identifiers, empty samples, pending payments and incomplete pages require review. No financial state is changed.

Results include a run ID, plan fingerprint, result digest, mapping, record counts, provenance and an audit event ID. Nexra persists the assessment metadata in workspace audit events without provider records or request inputs. Download the receipt in the Gateway console. fixture_sample_passed is deterministic test evidence; provider_sandbox_sample_passed is one credential-backed sandbox sample. Neither establishes complete pagination, provider certification, validated writes or production permission. Requalify after account, schema, mapping, policy or release changes. Receipts are observations, never execution grants.

Nexra Agent

The Gateway's Agent panel uses Nexra's server-side model service and the paid integration_plan entitlement. It does not provision or expose a model key. POST /api/console/gateway/applications/:applicationId/agent/chat accepts only message, optional conversationId, optional selected native workflow (flowId, versionId) and explicit operation selections from the workflow panel. Workspace and user authority come from the signed-in member. Application/project scope is resolved before invoking the model; existing conversations must belong to the selected application.

The model returns a strict bounded proposal: summary, question, workflowKey, optional nextAction and mappingProposal, and at most three bindings. Server validation rejects undeclared authority fields, invented operations, accounts absent from explicit selections and malformed output. The Agent never executes a provider operation, grants approval or publishes a flow. Missing AI configuration or entitlement fails visibly, without a synthetic fallback. Recent conversation messages are bounded, redacted context rather than authority. Review the resulting plan, run sandbox qualification samples and continue through native integration, mapping, approval, publication, deployment and monitoring controls.

Chat returns proposals only. Native lifecycle review, mapping previews and separately confirmed draft mapping, compilation, sandbox publication and repair controls are available through the contracts below. Separate confirmed deployment controls are available; approved-account acceptance remains pending. Local or fixture proof does not establish provider qualification.

Built-in describe_capability requests account capability discovery and labels schemaSource as account_discovery when the provider returns that operation's schema. Reviewed recipe and connection-owned private schemas are labelled separately. Missing or failed provider discovery is explicit: catalogue fallback is guidance, not account access proof. Discovery cannot override disabled writes, grant permissions or qualify a complete workflow.

For an explicitly bound lead_to_customer plan, the Workflow plans panel can create a native sandbox draft inside a selected integration in the application's project. POST /api/console/gateway/applications/:applicationId/workflows/drafts accepts workflowKey, two bindings, planFingerprint, integrationId and name. The server rechecks plan scope/fingerprint, flow create/edit permissions, integration project and active sandbox connections. Creation is one database transaction covering an inactive draft, initial version, five steps, four edges and an audit event. No provider call or schedule is created. Retries are disabled. The native compiler refuses the mapping-incomplete scaffold; configure mappings and validation, test approved sandbox data and use separate native publication/deployment controls. Draft creation is member-confirmed, never an authority grant from the model.

Complete native sandbox qualification

start_workflow_qualification queues the exact published native version using flowId, expectedRecords (1–10,000), idempotencyKey and correlationId. It binds the application/project, immutable version/checksum, connection configuration, credential reference metadata, policy and backend release. The worker checks the contract before dispatch and stops an oversized source before destination writes. Review the write operations explicitly before starting from the console. Native write enablement and current trial/runtime policy still apply.

get_workflow_qualification returns a terminal execution receipt requiring every runtime step, exact nonempty record counts, unique source/destination identifiers and governed destination evidence. fixture_workflow_passed proves a deterministic workflow; provider_sandbox_workflow_passed describes a credential-backed sandbox workflow. Neither grants production execution. The native worker's broader fan-out and concurrent-dispatch behavior still requires qualification; missing per-binding evidence is refused. The SDK exposes startWorkflowQualification and getWorkflowQualification. Keep the intended event key after an uncertain queue response and inspect its outcome before retrying.

Native lifecycle and mapping review

The shared Gateway has fourteen tools. Explicitly publish and grant inspect_workflow_lifecycle, preview_workflow_mapping and apply_workflow_action; an existing credential gains no new tools automatically. Inspection and preview need connect:read, and mutations need connect:execute plus the native member permission for that action. An active workspace member and the application's project scope are always required.

Select flowId and versionId to inspect status, bounded field/schema metadata, validation issues, schedules, observed run counts and allowed actions. No provider record values or credentials enter the Agent's lifecycle context. The returned fingerprint binds the review to current state and release. Ambiguous source/destination bindings require clarification rather than silently selecting the last provider in the flow.

The Agent may propose mappingProposal: { flowStepId, fields } only for an editable, unambiguous step. Each native field uses destinationPath, mappingType (direct, constant, default or transform), required, and the corresponding sourcePath, native transformation expression, constant or default value. Review and edit the JSON fields in the console; model output performs no save. preview_workflow_mapping accepts the selected flow/version, fingerprint, map step, one explicit record, and optional proposed fields. It validates against bound provider schemas and previews only that sample. Its user_supplied_mapping_sample evidence and qualification: not_run are separate from whole workflow qualification.

To save, call apply_workflow_action with action: "save_mapping", selection, fingerprint, confirmed: true and mapping: { flowStepId, fields }. Saving replaces only that draft step's mappings, invalidates compilation and requires a new review. Competing saves against the same reviewed compilation cannot both succeed. Published versions are immutable: first create a repair draft. In the console, changing fields, sample or selection clears the preview confirmation. Compile, publish and execute remain separate actions.

Other actions are compile, publish_sandbox and prepare_repair. Sandbox publication requires paused schedules and the reviewed compilation checksum; the publisher rechecks these inside its transaction. Repair clones a new sandbox draft while retaining the original published version. No action dispatches provider operations or grants production approval. After an uncertain response, inspect current state before repeating a mutation; repair-draft creation does not promise exactly-once delivery.

REST console endpoints share /api/console/gateway/applications/:applicationId/workflows/lifecycle/ with inspect, mapping-preview and action. The SDK methods are inspectWorkflowLifecycle, previewWorkflowMapping and applyWorkflowAction. Use the separate reviewed deployment tools or linked native controls for deployment approval, activation and rollback.

Deployment review in Agent lifecycle

Inspect a workflow version to see its integration environments and the latest revisions

for that flow. Each revision shows status, whether it uses your selected version,

approval/rejection counts and whether you created it. Observations are bounded to

20 environments, 20 revisions per environment and 100 approval decisions per revision;

truncated history is labelled. Deployment configuration, credentials and reviewer

comments are not supplied to the Agent. This section requires deployment read permission.

Use Review deployment controls to review the exact revision, request approval,

activate or roll back with native permissions. Approval requires another workspace

member. Chat and inspection perform no deployment action. Rollback revalidates the

published version and its environment before changing the current deployment.

Qualification across workflow branches

Compiled incoming edges now supply separate record snapshots to each branch. A branch's

mapping or transformation does not change another branch's input. Conflicting values

at a merge require an explicit merge definition rather than an automatic choice.

Destination success is recorded for each record and destination step. Qualification

requires the latest completed receipt and an observed output identifier at every

destination; an identifier from the final destination does not prove the others succeeded.

A later successful branch does not erase an earlier record failure. Inspect the exact

failed step and reconcile its provider outcome before repair or retry.

The local SQL fixture qualifies three records through two destinations with independent

branch transformations and six governed writes. A one-record destination failure remains

visible and requires review. This is deterministic fixture evidence, not a live-provider

qualification. Recovery across multiple failed branches and interrupted workers

remains a separate acceptance check; per-write dispatch protection does not promise

exactly-once provider execution.

Whole-run ownership and recovery

Nexra serializes each native execution and its dead-letter retries using a persistent

database claim. Concurrent processors cannot mutate the same run. An active claim

does not expire automatically: elapsed time does not prove a provider request has

stopped. Normal completion and handled errors release only the current owner's claim.

If a worker terminates unexpectedly, an administrator must establish that it has

stopped and reconcile provider/evidence outcomes before recovery. Per-write dispatch

claims still refuse unknown-outcome replays; whole-run ownership does not promise

exactly-once provider execution.

The native execution detail API returns processing.state (claimed or idle),

claimedAt and automaticTakeoverAllowed: false, without ownership tokens. The run

page explains a held claim and disables its retry button. The backend also blocks

dead-letter dispatch while that execution is held. Existing executions need no

schema migration. Local SQL fixtures prove competing initial claims, non-expiry,

worker exclusion, tenant denial and retry exclusion; they are not provider proof.

Repairing failures at multiple destinations

Recovery repairs one reviewed destination at a time. Each successful retry appends

a new per-step receipt with its observed provider identifier and preserves the

original failed receipt. If another destination still failed, the record remains

failed, its recovery entry points to that destination and retains that branch's

input. Review and request the next retry separately. A later repair cannot erase

another destination's failure. Run and step counts reflect the latest receipts.

Retries use atomic dispatch claims as well as whole-run ownership. A failed or

interrupted provider outcome cannot dispatch automatically again under the same

retry key. Missing destination receipts or missing returned identifiers require

review. Repair does not make an old qualification contract current: changes to

connection configuration, credentials, policies or release require qualification

again. Native qualification can observe governed retry results alongside original

flow results, while preserving its exact contract and per-destination checks.

Connect a provider account across interfaces

See Connect through MCP, APIs, CLI and SDKs for account setup, exact operation selection, authentication, copyable examples, sandbox boundaries and approval troubleshooting.

Reviewed deployment tools

inspect_workflow_deployment selects an exact flow, version and environment, with an optional exact revision. It returns a fingerprint and only currently permitted actions. apply_workflow_deployment requires that selection, unchanged fingerprint, explicit confirmed: true, and one of request, approve, reject, activate or rollback. Review and native mutation share a serializable transaction; stale authority or state refuses the action without automatic retry. The revision author cannot approve their own request. Activation and rollback affect the version used by future native runs; they make no immediate provider call.

Publish and grant these two new tools explicitly. External sensitive-tool execution also requires the MCP tool approval gate, with a stable metadata idempotency key and an independent approval ID. SDK inspectWorkflowDeployment and applyWorkflowDeployment share this contract; use gateway.call when supplying initial tool-approval metadata. Native deployment approval is distinct from tool approval. See Gateway API reference.

Complete bounded read qualification

Use the separately published qualify_complete_read_workflow tool for customer_invoice_lookup or invoice_reconciliation. In Gateway → Workflow plans, choose Complete bounded read query after binding both operations. Review the expected dataset counts, page bounds and field paths; the prefilled counts are examples.

{
  "workflowKey": "invoice_reconciliation",
  "bindings": [
    { "stepKey": "invoices", "connectionId": "<account>", "operationKey": "<invoice-read>" },
    { "stepKey": "payments", "connectionId": "<account>", "operationKey": "<payment-read>" }
  ],
  "inputs": {},
  "expectedRecords": { "invoices": 1, "payments": 2 },
  "maxPages": 3,
  "pageSize": 50,
  "mapping": {
    "leftIdentity": "id",
    "rightIdentity": "id",
    "rightReference": "invoiceId",
    "invoiceAmount": "amount",
    "paymentAmount": "amount",
    "invoiceCurrency": "currency",
    "paymentCurrency": "currency",
    "paymentStatus": "status",
    "settledStatuses": ["settled"]
  }
}

Replace the exact account, operation, fields and counts using reviewed connection contracts and approved sandbox data. The request starts at the selected query's beginning; top-level input cursor and limit are refused. The adapter translates its own normalised cursor into the provider's page, offset, link or cursor protocol. An undeclared list pagination contract cannot establish complete qualification. A single-object get may be bounded without pagination.

Nexra follows continuation pages sequentially, checks exact expected counts and unique record identities, and refuses repeated cursors, exceeded page/data bounds or unfinished pagination. Each step allows 0–2,000 expected records, 1–20 pages and a requested page size of 1–100; provider fixed page sizes still apply. No page is silently truncated. A failed provider page returns an error and no passing receipt.

Customer lookup permits multiple distinct invoices per customer and customers without invoices. Declare leftIdentity, rightIdentity, rightReference, invoiceCurrency, invoiceStatus and acceptedInvoiceStatuses. Unlinked invoices, duplicate identifiers, invalid currency or unaccepted status require review. Reconciliation aggregates distinct explicitly settled payments for each invoice in integer minor units, requiring matching currency and exact total. Duplicate, pending, partial, excess or orphaned payments require review.

The receipt binds the query, mapping, connection configuration/update timestamp, credential reference metadata, operation contracts and backend release. Nexra rechecks that fingerprint before pages and at completion. Receipts and audit events contain counts, page state, bindings and digests; provider records and credentials are excluded. fixture_complete_read_passed is deterministic evidence; provider_sandbox_complete_read_passed is one approved credential-backed selected-query observation. Neither guarantees a provider snapshot, proves every account record was returned, certifies a connector or grants production permission.

MCP and Gateway REST share this new tool; explicitly publish and grant it with connect:read and connect:execute. The SDK exposes gateway.qualifyCompleteReadWorkflow(request). The existing qualify_workflow remains a one-page sample and is labelled separately. Requalify after query, mapping, account configuration, credential or release changes.