Connect through MCP, APIs, CLI and SDKs

Set up the connection

Provider credentials remain in Nexra's secure connection references. Your client presents a Nexra credential, not the provider password. Private REST/OpenAPI connections follow the same project and permission boundaries; see custom connectors.

Check provider access before connecting

The connector's supported authentication method and operation schema determine the setup. Use its connection form and provider setup guide; do not assume every provider supports OAuth or the same fields.

A provider's catalogue entry does not establish availability in every country. Check account eligibility, API access, provider sandbox support and each operation's constraints. Keep the catalogue's All / Implemented / Planned filter: a planned entry expresses delivery intent and has no executable connection contract.

Which interface should I use?

A product sandbox key, a browser/CLI session and an MCP OAuth token serve different interfaces. A credential does not automatically work across all of them.

Shared connection and operation identifiers

Discover with search_capabilities, then inspect describe_capability using the returned connectionId and operationKey. Replace the placeholders below with those exact values; operation names vary by provider. Use resolve_capability when a business term has multiple possible meanings. An ambiguous result requires an explicit selection.

Gateway arguments for a read:

{
  "connectionId": "<connection-id-from-discovery>",
  "operationKey": "<operation-key-from-discovery>",
  "input": {}
}

Replace input with the described schema. recipe_fields operations accept declared provider fields directly. adapter_envelope operations retain their declared envelope, such as pathParameters, query, body, values or id. Empty input is valid only when the description says so.

MCP: connect an agent

Configure a Streamable HTTP client with this endpoint:

https://api.nexra.amakoragroup.com/mcp

An OAuth-capable client follows Nexra's sign-in and consent flow. Choose the application and published server you reviewed. A server-to-server client can exchange its MCP client credentials through /oauth/token or nexra mcp token. See MCP authentication and protocol for full setup.

Raw clients first send initialize, save the returned MCP-Session-Id, and send that header plus the negotiated MCP-Protocol-Version on later requests. Send notifications/initialized before listing or calling tools. tools/list shows the tools this credential can actually access.

After initialisation, call discovery:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_capabilities",
    "arguments": { "query": "customers", "mode": "read", "limit": 5 }
  }
}

Inspect the exact result in a separate call:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "describe_capability",
    "arguments": {
      "connectionId": "<connection-id-from-discovery>",
      "operationKey": "<operation-key-from-discovery>"
    }
  }
}

After reviewing the schema and confirming that the selected operation is a read, call execute_capability with the same selection and an input object matching that schema. Use a new request ID. Do not paste placeholder values or substitute an operation from another provider.

Then call describe_capability and execute_capability with the exact selection and described input. Sensitive calls carry approval metadata in params._meta, including "nexra/approvalRequestId" when required. Do not put approval metadata into operation input.

APIs: call the Gateway

Set NEXRA_API_ORIGIN to the API origin above, without /mcp, and obtain NEXRA_MCP_TOKEN from your authorised OAuth client or secret-backed token exchange. Gateway REST uses the same published tools, scopes, rate limits and approval policies as MCP.

curl --fail-with-body "$NEXRA_API_ORIGIN/api/gateway/tools/search_capabilities" \
  -H "Authorization: Bearer $NEXRA_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"arguments":{"query":"customers","mode":"read","limit":5},"meta":{}}'

Inspect the selected operation:

curl --fail-with-body "$NEXRA_API_ORIGIN/api/gateway/tools/describe_capability" \
  -H "Authorization: Bearer $NEXRA_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"arguments":{"connectionId":"<connection-id>","operationKey":"<operation-key>"},"meta":{}}'

After inspection, prepare read-request.json with the exact IDs and required read input. Replace every placeholder; {} is valid only for operations whose schema permits it.

{
  "arguments": {
    "connectionId": "<connection-id-from-discovery>",
    "operationKey": "<operation-key-from-discovery>",
    "input": {}
  },
  "meta": {}
}

curl --fail-with-body "$NEXRA_API_ORIGIN/api/gateway/tools/execute_capability" \
  -H "Authorization: Bearer $NEXRA_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @read-request.json

Execute with POST /api/gateway/tools/execute_capability and an envelope containing arguments: { connectionId, operationKey, input } and meta: {}. Results contain content text entries whose text is JSON. HTTP errors remain errors; inspect the status and response instead of treating them as successful records.

The console counterpart is POST /api/console/gateway/applications/{applicationId}/tools/{toolName}. It uses the signed-in member's workspace/project authority and returns the structured result directly. Do not use browser session tokens as MCP credentials. See Gateway contracts and Connect connection API.

Sensitive published-tool policies can also require a tool-level approval before execution. Start that request with meta["nexra/idempotencyKey"] and optional meta["nexra/correlationId"] (MCP uses params._meta). After independent approval, retry with "nexra/approvalRequestId". The generic SDK gateway.call(tool, arguments, meta) supports those metadata fields. Native deployment approval remains a separate requirement.

CLI: discover, test and run

Install the published CLI and choose a workspace:

npm install -g https://developer.amakoragroup.com/downloads/nexra-cli-0.3.0.tgz
nexra auth login
nexra context use --workspace <workspace-id> --environment sandbox
nexra connectors list --search salesforce
nexra connectors get salesforce
nexra connect connections list --output json
nexra connect connections test <connection-id>
nexra connect runs list --flow <flow-id>

Create and configure connections in the console, then use these commands to inspect them. Run a reviewed native flow with nexra connect flows run <flow-id> --environment sandbox --idempotency-key <stable-event-key>. Production requires an approved deployment. A timed-out run request needs inspection with the same key before another attempt.

To use Gateway REST from a terminal, set NEXRA_MCP_CLIENT_ID and NEXRA_MCP_CLIENT_SECRET through your secret store, then capture the token without printing it:

export NEXRA_MCP_TOKEN="$(nexra mcp token)"

Use that token in the REST examples above. There is currently no nexra gateway execute command. The CLI's signed-in session does not substitute for this MCP credential. See CLI commands, configuration and exit codes.

SDKs: use the shared Gateway client

Fetch GET /api/gateway/sdk/typescript on the API origin. Its JSON response includes two files, nexra-gateway.cjs and nexra-gateway.d.cts; save each file's content under its supplied name in the same directory. This is a download contract, not an npm package installation.

const { NexraGateway } = require("./nexra-gateway.cjs");
const gateway = new NexraGateway({
  baseUrl: process.env.NEXRA_API_ORIGIN,
  token: () => process.env.NEXRA_MCP_TOKEN,
});
const matches = await gateway.search("customers", { mode: "read", limit: 5 });
console.log(matches); // choose an exact account and operation
const selection = {
  connectionId: "<connection-id-from-discovery>",
  operationKey: "<operation-key-from-discovery>",
};
const description = await gateway.describe(selection);
console.log(description); // review schema before supplying input
// Run separately after reviewing the description:
// const result = await gateway.execute(selection, describedInput);

The client parses the MCP-compatible result envelope and throws on HTTP errors. It performs no automatic retries or pagination. Use gateway.compose, gateway.qualify, gateway.startWorkflowQualification and gateway.getWorkflowQualification for their distinct planning and qualification stages. Keep tokens server-side.

For product-specific clients, use Dashboard → SDKs, API Reference downloads, or nexra sdk generate --product <slug> --language <language> --wait. Those generated clients cover the published product API; they do not grant access to arbitrary provider operations. See SDK targets and downloads.

Sandbox, approvals and evidence

The API Sandbox executes assigned published API products through its controlled proxy. For connector capability exploration and sample qualification, use Nexra Connect → Gateway with a sandbox connection in the selected application's project. These are separate request paths with their own credential checks.

A Nexra sandbox connection can still call a real external account. Choose provider sandbox credentials where supported and inspect the environment and operation before execution. Deterministic demos label providerNetworkCall: false; they do not prove a real provider connection.

Start with bounded reads. Writes require explicit enabled operations, native permissions and applicable deployment/policy gates. A governed write may return approval_required; another authorised member must approve it. Retry only the unchanged reviewed input and stable idempotency key, placing the approval ID in REST meta, MCP params._meta or the SDK's approvalRequestId option. Expired approval, changed configuration or changed release requires fresh review. Never automatically replay an unknown provider outcome.

A mapping preview is user-supplied sample evidence. A read qualification sample does not prove complete pagination. Whole-workflow receipts check recorded execution against the exact published contract. Neither fixture evidence nor a sandbox receipt grants production approval. See Gateway qualification and recovery.

Sandbox walkthrough

To test a published product endpoint, use API Sandbox and that product's assigned credentials. To test the shared connector operation contract through an external client, use the MCP, Gateway REST or Gateway SDK examples above. Publishing tools and granting scopes are required before an external client can use them.

Diagnose connection failures