Development guide — Create an app from your IDE

This guide walks you through installing and configuring mcp-andes to work with ANDES directly from your editor (Cursor, Windsurf, VS Code with compatible agents, etc.). It matches the interactive guide in the ANDES platform.

What is mcp-andes?

mcp-andes is the main ANDES platform CLI. It connects your local environment to ANDES services and, through the Model Context Protocol (MCP), lets your IDE run actions such as creating applications, listing products, or installing skills without leaving the editor.

Prerequisites

Before you start, make sure you have:

• An editor that supports MCP servers (recommended: Cursor or Visual Studio Code)
• Corporate network access and Artifactory
• A LATAM account for Azure AD authentication

---

Step 1 — Install the uv package manager

We use uv to install mcp-andes in an isolated way without conflicts. For up-to-date instructions see the official uv documentation.

macOS / Linux:

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

Install uv on Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify the installation:

Verify uv

uv --version

---

Step 2 — Get an Artifactory token

You need a personal Artifactory token to install mcp-andes from LATAM's private index.

i. Access Artifactory

Go to https://artifactoryrepo1.appslatam.com/ui/login/ and sign in with your LATAM account using Google login.

ii. Generate a token

In the top-right corner open the User Menu, go to "Set me up", and select "pypi".

Then click "Generate token".

iii. Copy credentials

On the "install" tab you will see a variable like:

index-url = https://YOUR.USER:TOKEN@artifactoryrepo1.appslatam.com/...

Copy everything before the @ (i.e. YOUR.USER:TOKEN) — you will use it in the next steps.

---

Step 3 — Install and configure mcp-andes

Now we install the central ANDES tool. Follow these three sub-steps carefully.

i. Install from the terminal

Run the following command using the USER:TOKEN value you copied in the previous step (the part before @):

Install mcp-andes

uv tool install mcp-andes \
  --index-url "https://USER:TOKEN@artifactoryrepo1.appslatam.com/artifactory/api/pypi/zone_andesai/simple" \
  --extra-index-url "https://pypi.org/simple" \
  --force

ii. Configure PATH (one time only)

So your terminal recognizes the mcp-andes command, add the tools directory to your shell config:

Zsh (default on Mac):

PATH on Zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Bash (Linux / Windows Git Bash):

PATH on Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

iii. Final verification

Check that the tool is on your PATH:

Verify installation

which mcp-andes

Expected result: a path similar to /Users/your_name/.local/bin/mcp-andes.

---

Step 4 — Azure AD authentication

To enable application creation permissions, link your corporate account using Microsoft's Device Flow (no passwords stored locally).

i. Start the flow

Run:

Azure AD authentication

mcp-andes test-auth

ii. Device Flow sync

The terminal will show an 8-digit code and open a browser window:

1. Copy the code from the terminal.
2. Paste it on the Microsoft sign-in page.
3. Sign in with your company credentials.

iii. Confirmation

When the browser confirms success, return to the terminal. You should see something like:

Authentication successful

---

Step 5 — Configure the MCP server in your IDE

So your editor can talk to ANDES, we use uvx as the runtime. Keep your Artifactory credentials handy (USER:TOKEN from step 2).

i. IDE configuration

Each IDE has its own MCP config file:

IDE	Configuration file
Cursor	.cursor/mcp.json in the project root, or ~/.cursor/mcp.json for global config
Windsurf	~/.codeium/windsurf/mcp_config.json
Claude Code	~/.claude/claude_desktop_config.json

In Cursor you can also use: Settings → Cursor Settings → Tools & MCP → Add new MCP server.

Add this block to the appropriate file:

MCP configuration (mcp-andes)

{
  "mcpServers": {
    "mcp-andes": {
      "command": "uvx",
      "args": ["mcp-andes"],
      "env": {
        "UV_INDEX_URL": "https://USER:TOKEN@artifactoryrepo1.appslatam.com/artifactory/api/pypi/zone_andesai/simple",
        "UV_EXTRA_INDEX_URL": "https://pypi.org/simple"
      }
    }
  }
}

Replace USER:TOKEN with the value from step 2 (before @).

ii. Verification

Save, then restart or reload your IDE. In Cursor you should see mcp-andes under Installed MCP Servers with tools available to the agent.

Visual check

In Cursor go to Settings → Tools & MCP and confirm mcp-andes is listed as an installed, enabled server.

---

Step 6 — Download and install Skills

To develop with AndesDX, install the application lifecycle skill package. Download and extraction are handled automatically.

i. Run the command

Install lifecycle skill

mcp-andes install-skills platform/andesdx-app-lifecycle

ii. What happens internally

• Version resolution: the backend picks and downloads the latest stable version.
• File handling: a .tgz package is downloaded and extracted in your working directory.

iii. Custom version (optional)

Install specific version

mcp-andes install-skills platform/andesdx-app-lifecycle@1.2.0

---

Step 7 — Create your first app with the Agent

You are ready to use the platform from your editor chat. Describe what you need in natural language.

i. Check authentication

Before starting, ensure the MCP is loaded and your token is active. Expired sessions often cause failed prompts.

Verification commands

# Check authentication
mcp-andes test-auth

# Detailed token status
mcp-andes token-status

ii. Start the conversation

Open an empty folder in your IDE first. When the agent creates your app, it will clone the repository into that workspace.

Open a new AI chat and write a clear instruction.

Example prompts:

• "Show me my available products in AndesDX"
• "I want to create a new application in AndesDX"
• "Help me bootstrap a backend project with the platform standard"
• "Create a Spring Boot application named app-name in product product created in the portal"
• "Create a Python FastAPI application named app-name in product product created in the portal"
• "Promote my application name to production"

iii. Agent-assisted flow

During the chat the agent will guide you through:

1. Product selection: which AndesDX product to use.
2. Identity and naming: app name, template (stack), and project metadata.
3. Provisioning: resource creation and workflow monitoring (visible under Applications in the platform).
4. Local environment: repository clone ready for coding.

---

Useful commands

Action	Command
Token status	mcp-andes token-status
Refresh token	mcp-andes refresh-token
Force refresh	mcp-andes refresh-token --force
Log out	mcp-andes logout
Test connection	mcp-andes test-connection
Show config	mcp-andes config-info

---

Troubleshooting

mcp-andes not found in the terminal

Ensure $HOME/.local/bin is on your PATH and open a new terminal session:

which mcp-andes

Artifactory install errors

• Confirm you copied the full USER:TOKEN (before @).
• Generate a new token if the old one expired.
• Check connectivity to artifactoryrepo1.appslatam.com.

MCP server missing in the IDE

• Validate JSON syntax in the config file.
• Ensure UV_INDEX_URL has valid credentials.
• Restart or reload the IDE after saving.

Authentication or token issues

mcp-andes test-auth
mcp-andes token-status

---

Support

If you run into installation or configuration issues, contact LATAM Airlines Engineering Platform.