> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aient.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Customer MCP connections
> Attach approved tools from your remote MCP servers to Sparkles in one Aient environment.
# 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
1. Open **Settings → Environments** and choose the environment.
2. Select **MCP connections**, then **Add MCP connection**.
3. Enter a stable alias, display name, HTTPS endpoint, and authentication type. New connections are
disabled.
4. If authentication is required, enter the credential. Aient stores it in the organisation vault
and never displays it again.
5. Select **Discover tools**, review the server-derived list, select only the tools you trust for
autonomous read use, and confirm the approval.
6. 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`](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
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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. |