> ## 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.

# Connect Gemini CLI

> Gemini CLI setup methods, authentication and resource permissions.

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

## Goal

Configure Gemini CLI to reach the scoped StackShift MCP endpoint.

## Prerequisites

* A StackShift backend/dashboard with agent connections enabled.
* Gemini CLI HTTP OAuth support

## Workflow

<Steps>
  <Step>
    Open Settings > Agent connections and choose Gemini CLI.
  </Step>

  <Step>
    Add an HTTP server and run /mcp auth stackshift.
  </Step>

  <Step>
    Review the browser request, return destination, selected resources, requested actions, policy and expiry before granting access.
  </Step>

  <Step>
    Return to the client and inspect connection identity and authorized resources. Verify actual operation outcomes separately.
  </Step>
</Steps>

## Setup from the shared catalog

Add an HTTP server and run /mcp auth stackshift.

Open Settings > Agent connections and expand this client. Use the endpoint and resolved instructions shown by your StackShift instance. The templates below contain placeholders, not a deployed endpoint or credential.

* Setup methods: cli command, configuration.
* Supported local configuration scopes: project, user. Choose the scope deliberately before setup.

## Project setup with the CLI (next release)

Open the agent directory at stackshift.cloud/agents and choose your client. Its setup page gives the recommended order: install the tools, add the skill from a terminal in the project root, sign in to StackShift, open a new coding-agent session, then paste a task into its chat. Terminal commands and chat prompts are labelled separately. Prompt-assisted setup is available as an alternative. MCP connection guides remain available separately.

Use your existing coding agent in a repository. Fetch [https://stackshift.cloud/prompt.md](https://stackshift.cloud/prompt.md) for the guided setup, or install the StackShift CLI and run the command below. This installs bundled project-local guidance and leaves MCP configuration unchanged. It does not install the coding client, authenticate or create resources.

Guidance is installed in .gemini/skills/stackshift-cloud-operations. Repeat setup is safe when the installed files match. If they differ, preserve or move the existing folder before installing an updated version. Remove only that folder to uninstall. Restart the coding agent after setup.

The bundled repository-setup.md covers standalone Git/local source, application releases and monorepos, static/SSR frameworks, Node.js, Python, PHP/Laravel, Ruby/Rails, Go, Rust, Java and .NET, Dockerfiles/images, workers, schedules, Functions and build-only artifacts. It also routes managed sites and mobile projects to their owning workflows. It documents current native qualification restrictions; framework detection alone is not a support guarantee.

For applications using databases, Assets, S2 or Mail, the bundled application-services.md guides resource reuse/provisioning, SDK and driver integration, protected credentials, environment separation and end-to-end verification. Managed Assets needs no additional S2 bucket; Mail test keys cannot authorize other services.

Existing applications follow an adoption flow: inspect the repository, verify and reuse StackShift project bindings, preserve working external providers and make only the changes needed for the requested task. Installation alone does not deploy or migrate the app. Previews use safe dependency configuration; data migration, production DNS cutover and retiring the previous deployment are separately scoped and verified.

The recovery-and-cutover.md guide covers target identity, interrupted setup, missing secrets, monorepos, preview isolation, database migrations, persistent files, OAuth/webhooks, background jobs, concurrent changes, capability mismatches and safe skill updates. It provides verification and recovery steps; these instructions do not imply automatic platform enforcement.

Use stackshift auth status or stackshift auth login for account access. Native AI credits are not required for direct CLI operations; agent-provider and cloud resource charges still apply. Publish the CLI release containing setup agent before advertising this command as available.

```bash theme={null}
stackshift setup agent --client gemini-cli
```

## Fetch StackShift guidance through MCP

The connected agent can call the read-only skill\_read tool to fetch SKILL.md, references/external-connections.md and the linked task guides. The server introduces this tool during connection setup. No download, local skill installation or native AI credits are needed to read the guides. The client decides when to call tools; connection alone is not proof that it has read the skill.

Try this read-only prompt: Use StackShift’s skill\_read tool to fetch SKILL.md and references/external-connections.md. Follow the guidance to inspect my connection identity and list only my authorized resources. Do not change anything.

Reconnect your client to refresh discovery after an upgrade. Skill guidance does not change your granted resources, permissions or approval requirements.

## Optional local skill installation

Download [StackShift skill v3.4.5](https://stackshift.cloud/skills/stackshift-cloud-operations-3.4.5.zip) and its [SHA-256 checksum](https://stackshift.cloud/skills/stackshift-cloud-operations-3.4.5.zip.sha256). The package contains SKILL.md and all ten reference guides.

Extract the ZIP and place the entire stackshift-cloud-operations folder inside .gemini/skills/ in your project. Review the files first. Back up any existing installation before replacing it. Start a new agent session in that project and select the skill when your client requires it.

The skill guides workflows; MCP supplies tools and your consent supplies permissions. The package contains no credentials and grants no new access. Delete only the installed skill folder to uninstall it. MCP authorization remains separate.

[Client skill instructions](https://geminicli.com/docs/cli/skills/).

## Client command template

Replace \{endpoint} with your instance MCP URL and \{scope}, when present, with a supported scope. If the command requires REGISTERED\_PUBLIC\_CLIENT\_ID and REGISTERED\_CALLBACK\_PORT, first follow the public-client registration instructions in the connection API guide. Use the returned public identifier and the exact registered port. Complete the separate authentication instruction above. Never insert a credential into a command URL.

```bash theme={null}
gemini mcp add --transport http --scope {scope} stackshift {endpoint}
```

## Configuration entry template

This is the server entry, not a replacement for your entire configuration file. Preserve other entries and use the supported setup adapter when available.

Catalog configuration location: .gemini/settings.json. Server map: mcpServers. The resolved location depends on the selected local scope.

```json theme={null}
{
  "httpUrl": "{endpoint}"
}
```

## Authorization and access

Initial discovery requests read access. To create or change resources, authorize the required actions in the browser consent flow.

Complete the client authentication step after adding the server. In Settings > Agent connections, review authorized resources, permitted actions, expiry and last observed use. CLI diagnostics check connectivity; inspect the operation result to confirm a deployment completed.

## Official client references

Catalog documentation review date: 2026-10-01. Requirements may change; consult the linked client documentation.

* [Gemini CLI reference 1](https://geminicli.com/docs/tools/mcp-server/)

## Expected result

<Check>
  A connection with the explicitly consented access. Setup alone does not prove client authentication, deployment success or database readiness.
</Check>

## Common failures

<Warning>
  * Hosted clients cannot reach a loopback-only development endpoint.
  * A configured server may still require client authentication.
  * Read access does not authorize mutations. Never work around a denied action with a broader legacy credential.
</Warning>

## 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.