### Start Development Server

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Start the development server with hot reloading enabled for real-time updates.

```bash
pnpm run dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Install all necessary project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Logging Examples

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Shows examples of successful and failed credential loading messages logged to stderr.

```log
[INFO] Loaded ArgoCD token registry from "/etc/argocd-tokens/tokens.json" with 2 entries
[ERROR] Failed to read ArgoCD token registry file at "/path/not/found": ENOENT: no such file
```

--------------------------------

### Basic Single-Instance Deployment

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Configures environment variables for ArgoCD base URL and API token, then builds and starts the HTTP transport.

```bash
export ARGOCD_BASE_URL=https://argocd.example.com
export ARGOCD_API_TOKEN=argocd_token_abc123...
npm run build && npm start http
```

--------------------------------

### Multi-Instance Kubernetes Deployment

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Demonstrates creating a ConfigMap with a token registry and applying a deployment configuration for a multi-instance Kubernetes setup.

```bash
# Create ConfigMap with token registry
kubectl create configmap argocd-mcp-tokens --from-file=tokens.json

# Deploy with stateless mode
kubectl apply -f deployment.yaml
```

--------------------------------

### Get Argo CD Application by Name and Namespace

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Example of calling the 'get_application' tool to retrieve a specific application by its name and namespace.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_application",
    "arguments": {
      "applicationName": "my-app",
      "applicationNamespace": "argocd-apps"
    }
  }
}
```

--------------------------------

### Create Argo CD Application

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Example of calling the 'create_application' tool with a detailed application specification.

```json
{
  "method": "tools/call",
  "params": {
    "name": "create_application",
    "arguments": {
      "application": {
        "metadata": {
          "name": "new-app",
          "namespace": "argocd"
        },
        "spec": {
          "project": "default",
          "source": {
            "repoURL": "https://github.com/my-org/my-repo",
            "path": "manifests",
            "targetRevision": "main"
          },
          "syncPolicy": {
            "syncOptions": [],
            "automated": { "prune": true, "selfHeal": true },
            "retry": {
              "limit": 5,
              "backoff": {
                "duration": "5s",
                "maxDuration": "3m",
                "factor": 2
              }
            }
          },
          "destination": {
            "server": "https://kubernetes.default.svc",
            "namespace": "default"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Start HTTP Server with Default Port

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Starts the HTTP transport using the default port (3000).

```bash
npm start http
```

--------------------------------

### List Argo CD Applications with Search

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Example of calling the 'list_applications' tool with search parameters and a limit.

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_applications",
    "arguments": {
      "search": "production",
      "limit": 10
    }
  }
}
```

--------------------------------

### Start SSE Server with Default Port

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Starts the SSE transport using the default port (3000).

```bash
npm start sse
```

--------------------------------

### Start MCP with HTTP Stream Transport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Start the MCP server using HTTP Stream transport, recommended for production. It supports multiple clients and stateful deployments. Optional port and stateless flags can be provided.

```bash
npm start http [--port 3000] [--stateless]
```

--------------------------------

### Get Argo CD Application Workload Logs

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Example of calling the 'get_application_workload_logs' tool, requiring a resource reference and container name.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_application_workload_logs",
    "arguments": {
      "applicationName": "my-app",
      "applicationNamespace": "argocd",
      "resourceRef": {
        "uid": "abc-123",
        "kind": "Deployment",
        "namespace": "default",
        "name": "my-deployment",
        "version": "apps/v1",
        "group": "apps"
      },
      "container": "main"
    }
  }
}
```

--------------------------------

### Start MCP with SSE Transport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Initiate the MCP server with SSE transport, ideal for Server-Sent Events clients. Requires session affinity in multi-replica setups. An optional port can be specified.

```bash
npm start sse [--port 3000]
```

--------------------------------

### Sync Argo CD Application with Dry-Run

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Example of calling the 'sync_application' tool with dry-run and prune options enabled.

```json
{
  "method": "tools/call",
  "params": {
    "name": "sync_application",
    "arguments": {
      "applicationName": "my-app",
      "dryRun": true,
      "prune": true
    }
  }
}
```

--------------------------------

### Start MCP with Stdio Transport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Use this command to start the MCP server with Stdio transport. This is suitable for integrations like VS Code and single-client processes.

```bash
npm start stdio
```

--------------------------------

### Example of a valid token registry entry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/errors-and-exceptions.md

When using the token registry, each entry must contain both a 'baseUrl' and a 'token' field. This example shows the correct format.

```json
{ "baseUrl": "https://argo.example.com", "token": "token_abc123" }
```

--------------------------------

### Run Argo CD Resource Action

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Example of calling the 'run_resource_action' tool to perform an action like 'rollout-restart' on a specified resource.

```json
{
  "method": "tools/call",
  "params": {
    "name": "run_resource_action",
    "arguments": {
      "applicationName": "my-app",
      "applicationNamespace": "argocd",
      "resourceRef": {
        "uid": "abc-123",
        "kind": "Deployment",
        "namespace": "default",
        "name": "my-deployment",
        "version": "apps/v1",
        "group": "apps"
      },
      "action": "rollout-restart"
    }
  }
}
```

--------------------------------

### MCP for Argo CD Startup Commands

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Use these commands to start the MCP for Argo CD service with different transport methods. The default is stdio, while http and sse are suitable for production. Development uses hot reload.

```bash
# Stdio transport (default for editors)
npm start stdio
```

```bash
# HTTP transport (production)
npm start http --port 3000
npm start http --port 3000 --stateless
```

```bash
# SSE transport
npm start sse --port 3000
```

```bash
# Development with hot reload
npm run dev
```

--------------------------------

### Start SSE Server on Custom Port

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Configure the SSE transport to use a custom port using the --port flag.

```bash
npm start sse -- --port 4000
```

--------------------------------

### Start HTTP Server on Custom Port

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Configure the HTTP transport to use a custom port using the --port flag or the PORT environment variable.

```bash
npm start http -- --port 4000
```

```bash
PORT=4000 npm start http
```

--------------------------------

### Install Argo CD MCP Server in VS Code

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Configuration object for installing the Argo CD MCP server in VS Code via a vscode:mcp URI. This includes the server name, command, arguments, and environment variables for Argo CD connection.

```javascript
const config = JSON.stringify({
  "name": "argocd-mcp",
  "command": "npx",
  "args": ["argocd-mcp@latest", "stdio"],
  "env": {
    "ARGOCD_BASE_URL": "<argocd_url>",
    "ARGOCD_API_TOKEN": "<argocd_token>"
  }
});
const urlForWebsites = `vscode:mcp/install?${encodeURIComponent(config)}`;
// Github markdown does not allow linking to `vscode:` directly, so you can use our redirect:
const urlForGithub = `https://insiders.vscode.dev/redirect?url=${encodeURIComponent(urlForWebsites)}`;
```

--------------------------------

### Get Resource Actions

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Lists available actions that can be executed on a resource, such as restart or rollout-restart. Requires application details and a resource reference object containing UID, name, namespace, kind, version, and group.

```typescript
public async getResourceActions(
  applicationName: string,
  applicationNamespace: string,
  resourceRef: V1alpha1ResourceResult
): Promise<{ actions: V1alpha1ResourceAction[] }>
```

```typescript
const result = await client.getResourceActions('my-app', 'argocd', {
  uid: 'abc-123',
  name: 'my-deployment',
  namespace: 'default',
  kind: 'Deployment',
  version: 'apps/v1',
  group: 'apps'
});

result.actions?.forEach(action => {
  console.log(`Action: ${action.name} - ${action.disabled}`);
});
```

--------------------------------

### Example Client Library Error: Invalid URL Format

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/errors-and-exceptions.md

This error, originating from the HttpClient, indicates an issue with the provided base URL. Verify that the base URL is a valid format and that any relative paths can be correctly resolved.

```text
Invalid URL: <url>
```

--------------------------------

### connectHttpTransport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Starts an HTTP server using the MCP HTTP stream protocol. Supports both stateful mode (with session persistence) and stateless mode (no session affinity required).

```APIDOC
## connectHttpTransport(port, stateless?)

### Description
Starts an HTTP server using the MCP HTTP stream protocol. Supports both stateful mode (with session persistence) and stateless mode (no session affinity required).

**Stateful mode (default):**
- Server maintains in-memory session map
- First request must be `initialize` to obtain session ID
- Subsequent requests must include `mcp-session-id` header
- Suitable for single-instance deployments or with sticky sessions

**Stateless mode:**
- No session persistence; every request is self-contained
- Credentials must be supplied on every request (headers or env vars)
- Suitable for Kubernetes deployments with HPA and no sticky sessions

### Method
`export const connectHttpTransport(port: number, stateless: boolean = false): void`

### Parameters
#### Path Parameters
- **port** (number) - Required - Port to listen on
- **stateless** (boolean) - Optional - Default: `false` - Run in stateless mode (no session affinity)

### Environment Variables
- `ARGOCD_BASE_URL` (optional): Default base URL
- `ARGOCD_API_TOKEN` (optional): API token for the default base URL
- `ARGOCD_TOKEN_REGISTRY_PATH` (optional): Path to JSON token registry file

### Routes
- `GET /healthz` — Liveness endpoint; returns `{ status: "ok" }`
- `POST /mcp` — Main endpoint for JSON-RPC requests and initialization
- `GET /mcp` — Session-level SSE subscription (stateful mode only, returns 405 in stateless mode)
- `DELETE /mcp` — Session termination (stateful mode only, returns 405 in stateless mode)

### Example
```typescript
import { connectHttpTransport } from './server/transport.js';

// Stateful mode (default)
const port = parseInt(process.env.PORT || '3000');
connectHttpTransport(port);

// Stateless mode for Kubernetes
connectHttpTransport(port, true);
```
```

--------------------------------

### Start HTTP Server in Stateless Mode

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Enables stateless mode for the HTTP transport, which is recommended for Kubernetes deployments with HPA and no sticky sessions. In this mode, every request must include credentials.

```bash
npm start http -- --stateless
```

--------------------------------

### connectSSETransport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Starts an HTTP server using Server-Sent Events (SSE) transport. Each client connection creates a stateful session. Requires session affinity in multi-replica deployments.

```APIDOC
## connectSSETransport(port)

### Description
Starts an HTTP server using Server-Sent Events (SSE) transport. Each client connection creates a stateful session. Requires session affinity in multi-replica deployments.

### Method
`export const connectSSETransport(port: number): void`

### Parameters
#### Path Parameters
- **port** (number) - Required - Port to listen on for SSE connections

### Environment Variables
- `ARGOCD_BASE_URL` (optional): Default base URL
- `ARGOCD_API_TOKEN` (optional): API token for the default base URL
- `ARGOCD_TOKEN_REGISTRY_PATH` (optional): Path to JSON token registry file

### Routes
- `GET /sse` — Establishes SSE connection; returns session ID and starts event stream
- `POST /messages?sessionId={sessionId}` — Sends JSON-RPC requests and receives event stream responses

### Example
```typescript
import { connectSSETransport } from './server/transport.js';

const port = parseInt(process.env.PORT || '3000');
connectSSETransport(port);  // Runs on the specified port
```
```

--------------------------------

### Running MCP Server in Stateless Mode (Node)

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Start the MCP server with the --stateless flag to enable stateless mode, which is recommended for Kubernetes deployments with HPA. This mode removes session affinity requirements.

```bash
node dist/index.js http --stateless
```

--------------------------------

### Example Tool Call Validation Error: Missing Required Field

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/errors-and-exceptions.md

This error is triggered when a mandatory parameter for a tool is not supplied or is set to null/undefined. Always provide all required parameters as specified in the tool's documentation.

```text
Required field: applicationName
```

--------------------------------

### Example JSON-RPC Call with Overridden Base URL

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

This JSON-RPC request demonstrates how to override the default Argo CD base URL for a specific tool call. Ensure a registry token is configured for the overridden URL if it differs from the default.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_applications",
    "arguments": {
      "argocdBaseUrl": "https://argocd.other-cluster.example.com"
    }
  }
}
```

--------------------------------

### MCP for Argo CD Environment Variables

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Configure MCP for Argo CD using these environment variables. ARGOCD_BASE_URL and ARGOCD_API_TOKEN are required. Optional variables control multi-instance setups, read-only mode, and TLS validation.

```bash
# Required for operation
export ARGOCD_BASE_URL=https://argocd.example.com
export ARGOCD_API_TOKEN=argocd_token_abc123...
```

```bash
# Optional: multi-instance setup
export ARGOCD_TOKEN_REGISTRY_PATH=/etc/argocd-tokens/tokens.json
```

```bash
# Optional: read-only mode
export MCP_READ_ONLY=true
```

```bash
# Optional: disable TLS validation (dev only)
export NODE_TLS_REJECT_UNAUTHORIZED=0
```

--------------------------------

### Connect MCP Server via HTTP Transport (Stateful/Stateless)

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Starts an HTTP server using the MCP HTTP stream protocol. Supports stateful mode (default) for single instances or stateless mode for Kubernetes deployments.

```typescript
import { connectHttpTransport } from './server/transport.js';

// Stateful mode (default)
const port = parseInt(process.env.PORT || '3000');
connectHttpTransport(port);

// Stateless mode for Kubernetes
connectHttpTransport(port, true);
```

--------------------------------

### Single Instance Deployment (Stateless)

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

This pattern is for stateless single instance deployments. Ensure necessary configurations are provided.

```bash
export ARGOCD_BASE_URL=https://argocd.example.com
export ARGOCD_API_TOKEN=token...
npm start http --port 3000 --stateless
```

--------------------------------

### Run with Credentials and Token Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Combine default credentials and a token registry path for comprehensive configuration using the Makefile.

```bash
make dev \
  ARGOCD_BASE_URL=https://argo.example.com \
  ARGOCD_API_TOKEN=<token> \
  ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json
```

--------------------------------

### Single Instance Deployment (Stateful)

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Use this pattern for a single instance deployment where state is managed directly.

```bash
export ARGOCD_BASE_URL=https://argocd.example.com
export ARGOCD_API_TOKEN=token...
npm start http --port 3000
```

--------------------------------

### Run with Credentials

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Configure Argo CD base URL and API token for authentication when running with the Makefile.

```bash
make run ARGOCD_BASE_URL=https://argocd.example.com ARGOCD_API_TOKEN=<token>
```

```bash
make dev ARGOCD_BASE_URL=https://argocd.example.com ARGOCD_API_TOKEN=<token>
```

--------------------------------

### HTTP Client GET Request

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Performs a GET request to a specified URL with optional query parameters. Returns a promise that resolves with the HTTP response.

```typescript
public async get<R>(url: string, params?: SearchParams): Promise<HttpResponse<R>>
```

--------------------------------

### Global CLI Help

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Displays the global help information for the CLI.

```bash
npm start -- --help
```

--------------------------------

### HTTP Client Stream GET Request

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Streams a GET response, processing each JSON line with a provided callback function. Useful for handling large or continuous data streams.

```typescript
public async getStream<R>(
  url: string,
  params?: SearchParams,
  cb?: (chunk: R) => void
): Promise<void>
```

--------------------------------

### List Applications with Pagination

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Demonstrates how to list the first 10 applications matching a search term and how to fetch the next page of results. Use 'limit' and 'offset' for pagination.

```typescript
// List first 10 applications matching "production"
const result = await client.listApplications({
  search: 'production',
  limit: 10,
  offset: 0
});

// List next page
const page2 = await client.listApplications({
  search: 'production',
  limit: 10,
  offset: 10
});

if (result.metadata.hasMore) {
  console.log('More applications available');
}
```

--------------------------------

### Docker Deployment: Stateless with Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Deploy a stateless instance with a token registry using Docker. Mount the token registry file and specify its path.

```bash
# Stateless with registry
docker run -e ARGOCD_TOKEN_REGISTRY_PATH=/etc/tokens/registry.json \
  -v /path/tokens:/etc/tokens:ro \
  -p 3000:3000 \
  argoprojlabs/mcp-for-argocd http --stateless
```

--------------------------------

### Configure Both Default Instance and Token Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Combine a default ArgoCD instance configuration with a token registry for managing multiple instances.

```bash
make dev ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token> \
  ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json
```

--------------------------------

### Multi-Instance Deployment with Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Deploy multiple instances using a token registry for managing ArgoCD API tokens. The registry path should be specified.

```bash
export ARGOCD_TOKEN_REGISTRY_PATH=/etc/tokens.json
npm start http --port 3000 --stateless
```

--------------------------------

### Initialize MCP Server

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Instantiate the Server class with ArgoCD connection details. Supports multi-instance configurations using a token registry.

```typescript
import { Server } from './server/server.js';

const server = new Server({
  argocdBaseUrl: 'https://argocd.example.com',
  argocdApiToken: 'your-api-token'
});

// Or with token registry for multi-instance support:
const registryToken = tokenRegistryFromEnv();
const server = new Server({
  argocdBaseUrl: 'https://argocd-primary.example.com',
  argocdApiToken: 'primary-token',
  tokenRegistry: registryToken
});
```

--------------------------------

### Server Constructor

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Initializes a new MCP server instance, providing integration with an ArgoCD instance. Supports multi-instance configurations via a token registry.

```APIDOC
## Server Constructor

### Description
Creates a new MCP server with ArgoCD client integration. When a token registry is configured, allows targeting multiple ArgoCD instances. Tools are automatically registered during construction based on the `MCP_READ_ONLY` environment variable.

### Signature
```typescript
constructor(serverInfo: ServerInfo)
```

### Parameters
#### Path Parameters
- **serverInfo.argocdBaseUrl** (string) - Yes - Base URL of the ArgoCD instance
- **serverInfo.argocdApiToken** (string) - Yes - API token for ArgoCD authentication
- **serverInfo.tokenRegistry** (TokenRegistry) - No - Optional registry mapping base URLs to tokens for multi-instance support

### Returns
Server instance

### Example
```typescript
import { Server } from './server/server.js';

const server = new Server({
  argocdBaseUrl: 'https://argocd.example.com',
  argocdApiToken: 'your-api-token'
});

// Or with token registry for multi-instance support:
const registryToken = tokenRegistryFromEnv();
const server = new Server({
  argocdBaseUrl: 'https://argocd-primary.example.com',
  argocdApiToken: 'primary-token',
  tokenRegistry: registryToken
});
```
```

--------------------------------

### Get Application Events

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Returns Kubernetes events related to a specified application. An optional application namespace can be provided for more targeted retrieval.

```typescript
public async getApplicationEvents(
  applicationName: string,
  appNamespace?: string
): Promise<V1EventList>
```

```typescript
const events = await client.getApplicationEvents('my-app');

events.items?.forEach(event => {
  console.log(`${event.reason}: ${event.message}`);
});
```

--------------------------------

### Get Size of Token Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Returns the count of registered base URL to token mappings. Useful for checking if the registry is empty.

```typescript
if (registry.getSize() === 0) {
  console.log('No token registry configured');
}
```

--------------------------------

### Basic Docker Run

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Run the MCP for Argo CD container using Docker with basic Argo CD credentials.

```bash
docker run \
  -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e ARGOCD_API_TOKEN=<token> \
  -p 3000:3000 \
  argoprojlabs/mcp-for-argocd \
  http
```

--------------------------------

### Get Application Logs

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Retrieves the last 100 log entries for all workloads managed by a specific application. Ensure the client is initialized before use.

```typescript
const logs = await client.getApplicationLogs('my-app');

logs.forEach(entry => {
  console.log(`[${entry.timestamp}] ${entry.message}`);
});
```

--------------------------------

### Connect MCP Server via Stdio Transport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Starts the MCP server using stdio transport for editor integration. This function blocks indefinitely.

```typescript
import { connectStdioTransport } from './server/transport.js';

// Starts server and blocks indefinitely
connectStdioTransport();
```

--------------------------------

### HTTP Transport CLI Help

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Shows help information specific to the HTTP transport, including port and stateless options.

```bash
npm start http --help
```

--------------------------------

### Get Specific Resources

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Retrieves manifests for specific resources within an Argo CD application. Provide resource references to fetch targeted manifests.

```typescript
// Get specific resources
const resources = await client.getResources('my-app', 'argocd', [
  {
    uid: 'uid-1',
    kind: 'Deployment',
    namespace: 'default',
    name: 'my-deployment',
    version: 'apps/v1',
    group: 'apps'
  }
]);
```

--------------------------------

### Get Resource Events

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Retrieves events for a specific resource managed by an Argo CD application. Use this to inspect the event history of a particular resource.

```typescript
const events = await client.getResourceEvents('my-app', 'argocd', 'uid-123', 'default', 'my-pod');

events.items?.forEach(event => {
  console.log(`[${event.lastTimestamp}] ${event.reason}: ${event.message}`);
});
```

--------------------------------

### Docker Deployment: Basic HTTP

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Run a basic HTTP instance of MCP for ArgoCD using Docker. Environment variables for ArgoCD URL and token are required.

```bash
# Basic HTTP
docker run -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e ARGOCD_API_TOKEN=token... \
  -p 3000:3000 \
  argoprojlabs/mcp-for-argocd http
```

--------------------------------

### Get ArgoCD Application

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Retrieves detailed information about a specific ArgoCD application. Specify the application name and optionally its namespace if it's not in the default namespace.

```typescript
// Get from default namespace
const app = await client.getApplication('my-app');
```

```typescript
// Get from specific namespace
const app = await client.getApplication('my-app', {
  applicationNamespace: 'argocd-apps'
});
```

--------------------------------

### SSE Transport CLI Help

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Displays help for the SSE transport, including the port option.

```bash
npm start sse --help
```

--------------------------------

### tokenRegistryFromEnv(registryPath?)

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Loads a token registry from a JSON file, optionally specified by a path or the ARGOCD_TOKEN_REGISTRY_PATH environment variable. Used at server startup to initialize the global registry.

```APIDOC
## Function: tokenRegistryFromEnv(registryPath?)

### Description
Loads a token registry from a JSON file. Used at server startup to initialize the global registry. Returns an empty registry if no path is configured (allowing single-credential operation).

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
- **registryPath** (string) - Optional - Path to JSON token registry file. Defaults to `process.env.ARGOCD_TOKEN_REGISTRY_PATH`.

### Returns
TokenRegistry instance (empty if no path is configured)

### Throws
If the path is set but the file cannot be read or is malformed (fail-closed behavior)

### Fail-closed behavior
If the environment variable is set but the file is missing, unreadable, or malformed, the process throws immediately at startup rather than silently falling back. This prevents misconfigured registries from causing wrong-token-to-host routing.

### Example
```typescript
// In transport.ts
const tokenRegistry = tokenRegistryFromEnv();

// Or explicitly:
const tokenRegistry = tokenRegistryFromEnv('/etc/argocd/tokens.json');
```

### Token Registry File Format:
```json
[
  {
    "baseUrl": "https://argo-primary.example.com",
    "token": "argocd_token_abc123..."
  },
  {
    "baseUrl": "https://argo-secondary.example.com",
    "token": "argocd_token_xyz789..."
  }
]
```
Each entry maps a base URL to the token that should be used when calling that instance. Base URLs are normalized when loaded and when looked up, so trailing slashes and capitalization differences do not affect matching.
```

--------------------------------

### Get Resource Manifest

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Retrieves the manifest (YAML or JSON) of a specific managed resource within an application. Requires application details and a resource reference object.

```typescript
public async getResource(
  applicationName: string,
  applicationNamespace: string,
  resourceRef: V1alpha1ResourceResult
): Promise<string>  // YAML/JSON manifest
```

```typescript
const manifest = await client.getResource('my-app', 'argocd', {
  uid: 'abc-123',
  name: 'my-configmap',
  namespace: 'default',
  kind: 'ConfigMap',
  version: 'v1',
  group: ''
});

console.log(manifest);  // YAML/JSON output
```

--------------------------------

### Run with Token Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Use a token registry file for managing Argo CD tokens when running with the Makefile.

```bash
make run ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json
```

```bash
make dev ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json
```

--------------------------------

### Initialize Session for Stateful HTTP Mode

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Use this snippet to initiate a session with the MCP. It requires Content-Type, Accept, x-argocd-base-url, and x-argocd-api-token headers. The response will contain an 'mcp-session-id' header.

```bash
curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-argocd-base-url: https://argocd.example.com' \
  -H 'x-argocd-api-token: argocd_token_...' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "example-client",
        "version": "1.0"
      }
    }
  }'
```

--------------------------------

### createApplication

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Creates a new application resource. The `metadata.namespace` field determines where the Application will be created.

```APIDOC
## Method: createApplication(application)

### Description
Creates a new application resource. The `metadata.namespace` field determines where the Application will be created.

### Method
`createApplication`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **application** (V1alpha1Application) - Yes - Complete application resource to create

### Request Example
```typescript
const app = await client.createApplication({
  metadata: {
    name: 'new-app',
    namespace: 'argocd'
  },
  spec: {
    project: 'default',
    source: {
      repoURL: 'https://github.com/example/repo',
      path: 'manifests',
      targetRevision: 'main'
    },
    syncPolicy: {
      syncOptions: [],
      automated: {
        prune: true,
        selfHeal: true
      },
      retry: {
        limit: 5,
        backoff: {
          duration: '5s',
          maxDuration: '3m',
          factor: 2
        }
      }
    },
    destination: {
      server: 'https://kubernetes.default.svc',
      namespace: 'default'
    }
  }
});
```

### Response
#### Success Response
- **application** (V1alpha1Application) - The created application resource with server-generated fields
```

--------------------------------

### connectStdioTransport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Starts the MCP server using stdio transport. The server reads JSON-RPC requests from stdin and writes responses to stdout. This is the primary transport for editor integration.

```APIDOC
## connectStdioTransport()

### Description
Starts the MCP server using stdio transport. The server reads JSON-RPC requests from stdin and writes responses to stdout. This is the primary transport for editor integration (VS Code, Cursor, Claude Desktop).

### Method
`export const connectStdioTransport = (): void`

### Parameters
None

### Environment Variables
- `ARGOCD_BASE_URL` (optional): Default base URL for Argo CD instance
- `ARGOCD_API_TOKEN` (optional): API token for the default base URL
- `ARGOCD_TOKEN_REGISTRY_PATH` (optional): Path to JSON token registry file

### Example
```typescript
import { connectStdioTransport } from './server/transport.js';

// Starts server and blocks indefinitely
connectStdioTransport();
```
```

--------------------------------

### MCP for Argo CD HTTP Headers - Stateful Initialization

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Use these headers for stateful transport. First, initialize the session with credentials, then include the session ID in subsequent requests.

```bash
# Stateful mode: initialize first
curl -X POST http://localhost:3000/mcp \
  -H 'x-argocd-base-url: https://argocd.example.com' \
  -H 'x-argocd-api-token: token...' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'
```

```bash
# Then include session ID
curl -X POST http://localhost:3000/mcp \
  -H 'mcp-session-id: <session-id>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",...}'
```

--------------------------------

### Get Resource Actions

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Retrieves available actions for a specific resource within an Argo CD application. Useful for performing operations like restart or rollout-restart on resources.

```typescript
const actions = await client.getResourceActions('my-app', 'argocd', {
  uid: 'uid-123',
  kind: 'Deployment',
  namespace: 'default',
  name: 'my-deployment',
  version: 'apps/v1',
  group: 'apps'
});

actions.actions?.forEach(action => {
  console.log(`Available action: ${action.name}`);
});
```

--------------------------------

### Get All Resources

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Retrieves all resource manifests managed by an Argo CD application. Call this without resource references to fetch all resources from the application's resource tree.

```typescript
// Get all resources (auto-fetches from resource tree)
const allResources = await client.getResources('my-app', 'argocd');
```

--------------------------------

### Get Pod Logs

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Retrieves the last 100 log entries from a specific pod within an application. Ensure the application name and pod name are correctly provided.

```typescript
public async getPodLogs(
  applicationName: string,
  podName: string
): Promise<ApplicationLogEntry[]>
```

```typescript
const logs = await client.getPodLogs('my-app', 'my-app-abc123-xyz');

logs.forEach(entry => {
  console.log(entry.message);
});
```

--------------------------------

### Get Resource Events

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Retrieves Kubernetes events for a specific resource managed by an application. Ensure you have the application name, namespace, resource UID, resource namespace, and resource name.

```typescript
public async getResourceEvents(
  applicationName: string,
  applicationNamespace: string,
  resourceUID: string,
  resourceNamespace: string,
  resourceName: string
): Promise<V1EventList>
```

```typescript
const events = await client.getResourceEvents(
  'my-app',
  'argocd',
  'uid-123',
  'default',
  'my-deployment'
);

events.items?.forEach(event => {
  console.log(`[${event.lastTimestamp}] ${event.reason}`);
});
```

--------------------------------

### Get Application Resource Tree

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Retrieves a hierarchical view of all resources managed by a specific Argo CD application. Use this to understand the structure of an application's deployed resources.

```typescript
public async getApplicationResourceTree(
  applicationName: string,
  appNamespace?: string
): Promise<V1alpha1ApplicationTree>
```

```typescript
const tree = await client.getApplicationResourceTree('my-app');

tree.nodes?.forEach(node => {
  console.log(`${node.kind}/${node.name}`);
  if (node.health) {
    console.log(`  Health: ${node.health.status}`);
  }
});
```

--------------------------------

### List ArgoCD Applications

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/errors-and-exceptions.md

List all applications in ArgoCD to verify application names and spelling.

```bash
list_applications
```

--------------------------------

### Get Token from Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Retrieves the token for a given base URL. Base URLs are normalized before lookup, handling minor formatting differences. Returns undefined if the base URL is not found.

```typescript
const token = registry.getToken('https://argo-primary.example.com');
// Returns: 'token-a'

const missing = registry.getToken('https://unknown.example.com');
// Returns: undefined
```

--------------------------------

### Argo CD Resource Reference Schema

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/quick-reference.md

Schema for referencing Kubernetes resources within Argo CD. Used for actions like getting workload logs or running resource actions.

```typescript
{
  uid: "abc-123-def",
  kind: "Deployment",          // or Pod, StatefulSet, etc.
  namespace: "default",
  name: "my-deployment",
  version: "apps/v1",          // or "v1" for core API
  group: "apps"                // or "" for core API
}
```

--------------------------------

### createServer Helper Function

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

A factory function to create and return a new Server instance, offering a convenient alternative to direct constructor usage.

```APIDOC
## createServer Helper Function

### Description
Factory function that instantiates and returns a Server. Provides a convenient alternative to direct constructor invocation.

### Signature
```typescript
function createServer(serverInfo: ServerInfo): Server
```

### Parameters
#### Path Parameters
- **serverInfo** (ServerInfo) - Yes - Configuration object matching Server constructor

### Returns
New Server instance

### Example
```typescript
import { createServer } from './server/server.js';

const server = createServer({
  argocdBaseUrl: process.env.ARGOCD_BASE_URL || '',
  argocdApiToken: process.env.ARGOCD_API_TOKEN || ''
});

// Now connect transport and use tools
```
```

--------------------------------

### Get Application Events

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Retrieves Kubernetes events related to a specific Argo CD application. This is helpful for diagnosing synchronization issues or other operational problems. The applicationNamespace is optional if the application resides in the default namespace.

```typescript
const events = await client.getApplicationEvents('my-app');

events.items?.forEach(event => {
  console.log(`${event.reason}: ${event.message}`);
});
```

--------------------------------

### Connect MCP Server via SSE Transport

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/transport-and-credentials.md

Starts an HTTP server using Server-Sent Events (SSE) transport on a specified port. This function blocks indefinitely and requires session affinity in multi-replica deployments.

```typescript
import { connectSSETransport } from './server/transport.js';

const port = parseInt(process.env.PORT || '3000');
connectSSETransport(port);  // Runs on the specified port
```

--------------------------------

### Configure ArgoCD Credentials via Token Registry

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Use a token registry file to manage API tokens for multiple ArgoCD instances.

```bash
make run ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json
```

--------------------------------

### createApplication

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-server.md

Creates a new Argo CD application resource within a specified namespace. This function allows for the definition of application source, sync policies, and destination cluster details.

```APIDOC
## create_application

### Description
Creates a new Argo CD application.

### Arguments Schema
#### Request Body
- **application** (V1alpha1Application) - Yes - Application resource specification with metadata.name, metadata.namespace, spec.project, spec.source, spec.syncPolicy, and spec.destination
- **argocdBaseUrl** (string) - No - Override the default base URL for this call

### Returns
- **V1alpha1Application** - The created Application resource specification.

### Throws
When `MCP_READ_ONLY=true` is set, this tool is not registered.

### Description
Creates a new Application resource. The `metadata.namespace` field determines where the Application resource will be created (e.g., "argocd", "argocd-apps", or any custom namespace).

### Example
```typescript
const newApp = await client.createApplication({
  metadata: {
    name: 'my-new-app',
    namespace: 'argocd'
  },
  spec: {
    project: 'default',
    source: {
      repoURL: 'https://github.com/my-org/my-repo',
      path: 'k8s',
      targetRevision: 'main'
    },
    syncPolicy: {
      syncOptions: [],
      automated: {
        prune: true,
        selfHeal: true
      },
      retry: {
        limit: 5,
        backoff: {
          duration: '5s',
          maxDuration: '3m',
          factor: 2
        }
      }
    },
    destination: {
      server: 'https://kubernetes.default.svc',
      namespace: 'default'
    }
  }
});
```
```

--------------------------------

### Configure ArgoCD Credentials via Environment Variables

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/README.md

Set environment variables to configure the default ArgoCD instance URL and API token for the MCP server.

```bash
make run ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token>
```

--------------------------------

### Example Tool Call Validation Error: Invalid Parameter Type

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/errors-and-exceptions.md

This error occurs when a tool argument's data type does not match the expected schema. Ensure all parameter types align with the schema definitions.

```text
Expected string, received number
```

--------------------------------

### ServerInfo

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/types.md

Configuration object passed to the Server constructor, including default base URL, API token, and an optional token registry.

```APIDOC
## ServerInfo

### Description
Configuration object passed to the Server constructor.

### Fields
- **argocdBaseUrl** (string) - Required - Default base URL for the session
- **argocdApiToken** (string) - Required - Default API token for the session
- **tokenRegistry** (TokenRegistry) - Optional - Registry for multi-instance token mapping
```

--------------------------------

### Build and Run HTTP Transport (Stateful)

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/configuration.md

Use this Makefile target to build and run the HTTP transport in stateful mode for local development.

```bash
make run
```

--------------------------------

### Instantiate ArgoCDClient

Source: https://github.com/argoproj-labs/mcp-for-argocd/blob/main/_autodocs/api-reference-client.md

Creates a new client instance for interacting with the Argo CD API. Requires the base URL of the Argo CD instance and an API token for authentication.

```typescript
import { ArgoCDClient } from './argocd/client.js';

const client = new ArgoCDClient(
  'https://argocd.example.com',
  'argocd_token_abc123...'
);
```