Customer MCP connections

Connect a remote MCP server that your organisation operates or trusts, review its tools, and let Sparkles use an approved subset in one Aient environment. This feature makes Aient the MCP client. It is different from connecting Codex, Claude, or another MCP client to Aient’s own https://aient.ai/mcp server.

Customer connections are scoped to one environment. A Production connection is not visible to tasks in Development, and there is no organisation-wide fallback.

Before you start

Your server must expose MCP Streamable HTTP at a public HTTPS URL on port 443. Aient supports:

no authentication;
a bearer token; or
one API-key header, such as X-API-Key.

Private-network addresses, redirects, query strings, URL fragments, URL credentials, arbitrary ports, local stdio processes, and arbitrary header maps are not supported. You must be an organisation owner or administrator. Keep the remote server’s tools safe for the autonomous read access you intend to approve.

Connect through the UI

Open Settings → Environments and choose the environment.
Select MCP connections, then Add MCP connection.
Enter a stable alias, display name, HTTPS endpoint, and authentication type. New connections are disabled.
If authentication is required, enter the credential. Aient stores it in the organisation vault and never displays it again.
Select Discover tools, review the server-derived list, select only the tools you trust for autonomous read use, and confirm the approval.
Enable the connection.

Approval and enablement are separate. A connection becomes ready only when it is enabled, has a current approved manifest, and has a valid credential when its authentication type requires one.

What Sparkles receives

At the start of a new task, Aient resolves the ready connections for that task’s exact organisation and environment. Sparkles receives only a bounded snapshot containing approved tool names, descriptions, and schemas. It does not receive the endpoint, credential, secret reference, or a live MCP client. Before every tool call, Pulse verifies that the connection is still enabled and that its revision and approved manifest still match the task snapshot. A changed, disabled, or deleted connection fails closed. The remote call then runs once through Aient’s protected egress path. Aient does not automatically retry an ambiguous tool call.

Readiness states

State	Meaning	Next action
`ready`	Enabled with a current approval and required credential	Start a new Sparkles task in this environment.
`disabled`	Configuration may be valid, but agents cannot receive it	Enable after reviewing the current approval.
`credential_missing`	Bearer or API-key auth has no usable credential	Attach or replace the credential.
`approval_missing`	No tools have been approved	Discover, select, and approve tools.
`approval_stale`	Endpoint or authentication configuration changed after approval	Discover and approve the current manifest again.

Readiness is derived from the current configuration; it is not a separate status that can drift from the connection.

Manage through the public API

The OpenAPI 3.1.1 document is available at https://aient.ai/api/v1/openapi.json. Use an Aient API key provisioned with mcp_connections:read for list/get or mcp_connections:manage for lifecycle operations. The current API-key dialog does not expose these permissions, so prefer audience-bound Aient CLI OAuth for customer automation unless an owner/admin has provisioned the key through the authenticated key API. Browser session cookies are not accepted on /api/v1.

Operation	HTTP request
List / create	`GET` / `POST /api/v1/environments/{environmentId}/mcp-connections`
Get / update / delete	`GET` / `PATCH` / `DELETE /api/v1/environments/{environmentId}/mcp-connections/{connectionId}`
Discover	`POST .../{connectionId}/discoveries`
Approve tools	`POST .../{connectionId}/tool-approvals`
Enable or disable	`PUT .../{connectionId}/enablement`
Set or rotate credential	`PUT .../{connectionId}/credential`
Preview deletion	`POST .../{connectionId}/deletion-previews`

Create and every mutation require an Idempotency-Key. Mutations of an existing connection also require If-Match with the quoted numeric revision returned by the latest read, for example If-Match: "4". Re-read after a 412 revision conflict instead of overwriting newer changes. The credential request body is write-only. Responses contain endpointOrigin and auth.credentialReady, never the full stored endpoint path, vault identifier, or credential.

Example: create a disabled connection

curl --request POST \
  "https://aient.ai/api/v1/environments/${AIENT_ENVIRONMENT_ID}/mcp-connections" \
  --header "Authorization: Bearer ${AIENT_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: setup-customer-tools-01" \
  --data '{
    "alias": "customer-tools",
    "displayName": "Customer tools",
    "endpointUrl": "https://mcp.example.com/mcp",
    "auth": { "kind": "bearer" }
  }'

The response is a disabled, credential-free connection at revision 1. Attach the credential before discovery.

Manage through the Aient CLI

The CLI command family is:

aient environment mcp list|get|create|update|discover|approve|enable|disable|delete
aient environment mcp credential set

Every command requires --environment with the environment UUID. Use --json for structured automation. Lists support --page-size, --cursor, and --all. Mutations require --revision; the CLI generates and reports an idempotency key when you do not provide one. Credentials are accepted only from stdin:

printf '%s' "${CUSTOMER_MCP_TOKEN}" | \
  aient environment mcp credential set mcp_... \
    --environment "${AIENT_ENVIRONMENT_ID}" \
    --revision 1 \
    --stdin

The customer MCP command family was merged after Aient CLI 0.10.2 and will be included in the next CLI release. If aient environment mcp --help is unavailable, use the UI, public API, or Aient MCP management tools until you upgrade.

An OAuth profile created before the MCP scopes were introduced must run aient auth login again. The CLI calls the public REST API; it does not send these commands through Aient’s inbound MCP server.

Manage through Aient MCP

An agent connected to https://aient.ai/mcp can use:

list_mcp_connections and get_mcp_connection;
create_mcp_connection and update_mcp_connection;
discover_mcp_connection_tools and approve_mcp_connection_tools;
set_mcp_connection_enabled;
preview_mcp_connection_deletion and delete_mcp_connection; and
prepare_mcp_connection_credential_upload.

Writes require aient.mcp.write. The management tools return concise text plus structured, redacted results. They never accept a reusable credential as model-visible input. For a credential, prepare_mcp_connection_credential_upload creates a short-lived, single-use browser action bound to the same user, environment, connection, and revision. Open that action as the signed-in human owner, then let the MCP client poll the same request. Never paste the credential into chat.

Updating, rotating, and deleting

Disable a connection before changing its endpoint or authentication configuration. Those changes clear the old approval.
Credential rotation validates the candidate before replacing the live secret. A failed candidate leaves the current credential in place.
Disable before deletion. Preview deletion first, inspect the approved-tool and credential effects, then confirm with the short-lived receipt.
A configuration change does not rewrite a task already in progress. Its schema stays stable, but a later call fails if the connection no longer matches; a new task resolves the new configuration.

Current limits

An environment may have at most 8 ready connections and 64 ready customer tools. One connection may approve at most 128 tools. Aient also bounds schema size and depth, descriptions, task snapshots, remote responses, and normalized tool results. If discovery exceeds a limit, reduce the server’s exposed tool catalog before trying again.

Troubleshooting

Problem	Resolution
`403` from the CLI or API	Sign in again for the new OAuth scopes, or use an API key already provisioned with the required MCP permission. Confirm the caller is an owner/admin in the environment’s organisation.
Endpoint rejected	Use canonical public HTTPS on port 443 with no query, fragment, redirect, URL credentials, or private address.
`revision_conflict` / HTTP `412`	Get the connection again and repeat the deliberate change using its current revision.
`manifest_changed`	Discover again, review the new manifest, and approve a fresh subset.
`credential_required` or `remote_auth_failed`	Attach or rotate the credential through UI, API/CLI secret-safe ingress, or the MCP browser handoff.
Connection enabled but absent from an old task	Start a new task. Existing tasks keep their task-frozen attachment snapshot.

Reference

Changelog

Customer MCP connections

Customer MCP connections

Before you start

Connect through the UI

What Sparkles receives

Readiness states

Manage through the public API

Example: create a disabled connection

Manage through the Aient CLI

Manage through Aient MCP

Updating, rotating, and deleting

Current limits

Troubleshooting

​Customer MCP connections

​Before you start

​Connect through the UI

​What Sparkles receives

​Readiness states

​Manage through the public API

​Example: create a disabled connection

​Manage through the Aient CLI

​Manage through Aient MCP

​Updating, rotating, and deleting

​Current limits

​Troubleshooting

Customer MCP connections

Before you start

Connect through the UI

What Sparkles receives

Readiness states

Manage through the public API

Example: create a disabled connection

Manage through the Aient CLI

Manage through Aient MCP

Updating, rotating, and deleting

Current limits

Troubleshooting