> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up and diagnose agent connections with the CLI

> Preview client setup, safely manage local configuration and inspect scoped connection access.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Configure a supported client without confusing local installation, owner consent and verified client use.

## Prerequisites

* A compatible Stackshift CLI build and an active profile pointing to the intended backend.
* The canonical client ID and a supported explicit local scope from its generated client guide.
* For doctor, a scoped connection credential configured through the CLI’s supported credential mechanism. An owner profile alone is not a connection grant.
* Check the installed CLI help for the setup commands supported by your version.

## Workflow

<Steps>
  <Step>
    Inspect the client catalog and preview setup for the intended client and local scope.
  </Step>

  <Step>
    Use the returned supported instructions, or explicitly apply a supported local configuration merge.
  </Step>

  <Step>
    Complete client authentication and browser consent, selecting resources and actions explicitly.
  </Step>

  <Step>
    Run doctor with scoped connection credentials to check authority and diagnostic transport.
  </Step>

  <Step>
    Remove a managed configuration entry when no longer needed, and revoke its connection separately.
  </Step>
</Steps>

## Inspect and preview setup

The CLI, dashboard and generated client guides use the same versioned catalog. Use its canonical IDs and supported scopes; unsupported clients or silently inferred local scopes are rejected.

Setup prints instructions by default. The endpoint comes from the active profile’s API URL. Selecting a profile does not authorize an MCP client to use that profile’s resources.

```bash theme={null}
stackshift agent client catalog
stackshift agent action-catalog
stackshift agent action-inventory
stackshift agent setup --client codex --scope user
```

## Apply a supported local configuration

Add --apply only when you intend to write local configuration. Supported merges preserve unrelated entries and retain backup and ownership evidence. They do not complete OAuth or grant resource access.

Use --directory for an explicit project directory where supported, or --config-file for an explicit configuration path. Codex respects CODEX\_HOME when no configuration path override is supplied.

Hosted clients and clients requiring their official CLI return supported setup instructions. Do not use --apply to imply that a hosted connector was installed. Follow the selected client guide to authenticate after configuration.

```bash theme={null}
stackshift agent setup --client codex --scope user --apply
```

## Run scoped diagnostics

Doctor compares catalog versions, reads connection identity and permitted resources, inspects an available resource context, and performs diagnostic MCP initialization and tool listing. A grant without an existing resource reports resource-context verification as unavailable.

The --client selection validates the catalog entry and reports its setup requirements. Doctor does not launch that client, verify its software identity or update observed client use. A successful diagnostic run is not evidence of a database-backed deployment.

If identity fails, check that the intended scoped connection credential is configured, has not expired or been revoked, and points to the correct backend. A missing action scope requires new explicit owner consent; doctor cannot broaden authority.

```bash theme={null}
stackshift agent doctor --client codex
```

## Remove configuration and revoke access

Removal deletes only the unchanged entry managed by Stackshift. If the entry was edited or cannot be verified as managed, inspect it rather than deleting unrelated client configuration. Use the same scope and path overrides used during setup.

Remove hosted connectors through their own client interface. Local removal and client disconnection do not revoke the server grant: revoke the retained connection in Settings → Agent connections. Revocation does not delete existing resources or promise that an already-dispatched controller stopped.

The nested agent client setup/remove CLIENT forms remain compatible. New workflows should use agent setup/doctor/remove --client with the required explicit scope for local configuration.

```bash theme={null}
stackshift agent remove --client codex --scope user
```

## Expected result

<Check>
  Local setup is repeatable and preserves unrelated configuration. Diagnostics describe checked access without claiming that the selected client authenticated.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="Connect your coding agent" href="/ai-features/agent-connections">
    Connect an external client, choose its access and inspect its work in StackShift.
  </Card>

  <Card title="Connection access and approvals" href="/ai-features/agent-connection-access">
    Understand selected resources, permitted actions, owner decisions and revocation.
  </Card>

  <Card title="Agent connection API and OAuth" href="/ai-features/agent-connection-api">
    Separate owner governance from scoped execution, handle OAuth challenges and recover recorded operations.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.