# CLI: MCPs Export

This guide covers exporting MCP configurations using the CLI with secure authentication handling.

## Overview

The `aip mcps get` command includes export functionality that creates import-ready configuration files with proper authentication handling.

## Basic Usage

### Export to JSON

```bash
aip mcps get <mcp-id> --export mcp.json
```

### Export to YAML

```bash
aip mcps get <mcp-id> --export mcp.yaml
```

Format is automatically detected from the file extension (`.json` or `.yaml`/`.yml`).

## Authentication Secret Handling

When exporting MCPs with authentication, the CLI provides secure handling for secrets:

### Interactive Mode (Default)

In terminal environments (TTY), you'll be prompted to enter missing or redacted secrets:

```bash
aip mcps get my-mcp --export mcp.json
```

Example prompt:

```
Bearer token is missing or redacted. Please provide the token.
Bearer token (leave blank for placeholder):
```

* Press Enter without input to use the placeholder `<INSERT VALUE>`
* Enter the actual secret to include it in the export (use with caution)

### Non-Interactive Mode

For batch operations, CI/CD pipelines, or automated scripts, use `--no-auth-prompt`:

```bash
aip mcps get my-mcp --export mcp.json --no-auth-prompt
```

This automatically uses placeholders without prompting, preventing the command from hanging.

### Custom Placeholders

Customize the placeholder text for team conventions or tracking:

```bash
aip mcps get my-mcp --export mcp.json \
  --no-auth-prompt \
  --auth-placeholder "TODO_ADD_SECRET_HERE"
```

## Export Behavior

### Schema Alignment

Exported files match the [documented MCP schema](https://gdplabs.gitbook.io/gl-aip/resources/reference/schemas/model-context-protocol-mcp):

* No internal fields (e.g., `framework`, `version`, `_client`)
* Clean structure ready for version control
* Compatible with import operations

### Secret Handling by Auth Type

Bearer Token (`bearer-token`):

```json
{
  "type": "bearer-token",
  "token": "<INSERT VALUE>"
}
```

API Key (`api-key`):

```json
{
  "type": "api-key",
  "key": "X-API-Key",
  "value": "<INSERT VALUE>"
}
```

Custom Headers (`custom-header`):

```json
{
  "type": "custom-header",
  "headers": {
    "X-API-Key": "<INSERT VALUE>",
    "X-Client-ID": "<INSERT VALUE>"
  }
}
```

### Format Detection

* `.json` → JSON format with 2-space indentation
* `.yaml` or `.yml` → YAML format with proper structure
* Multi-line strings (e.g., instructions) use literal block style (`|`)

## Complete Examples

### Example 1: Interactive Export

```bash
# Terminal session
$ aip mcps get prod-analytics --export mcp.json

Bearer token is missing or redacted. Please provide the token.
Bearer token (leave blank for placeholder): [ENTER]

✅ Complete MCP configuration exported to: mcp.json (format: json)
```

### Example 2: CI/CD Pipeline

```bash
# In .gitlab-ci.yml or GitHub Actions
aip mcps get $MCP_ID \
  --export config/mcp.json \
  --no-auth-prompt \
  --auth-placeholder "\${MCP_AUTH_TOKEN}"
```

### Example 3: Team Documentation

```bash
# Generate template for onboarding docs
aip mcps get team-mcp \
  --export docs/mcp-template.yaml \
  --no-auth-prompt \
  --auth-placeholder "CONTACT_OPS_TEAM"
```

## Example Exported MCP

### JSON Format

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "production-analytics",
  "description": "Analytics MCP for production environment",
  "transport": "http",
  "config": {
    "url": "https://analytics.example.com/mcp",
    "timeout": 30
  },
  "authentication": {
    "type": "api-key",
    "key": "X-API-Key",
    "value": "<INSERT VALUE>"
  },
  "mcp_metadata": {
    "environment": "production",
    "team": "data-science"
  }
}
```

### YAML Format

```yaml
id: 550e8400-e29b-41d4-a716-446655440000
name: production-analytics
description: Analytics MCP for production environment
transport: http
config:
  url: https://analytics.example.com/mcp
  timeout: 30
authentication:
  type: api-key
  key: X-API-Key
  value: <INSERT VALUE>
mcp_metadata:
  environment: production
  team: data-science
```

## Use Cases

{% stepper %}
{% step %}

### Version Control

Export MCPs for GitOps workflows:

```bash
aip mcps get prod-mcp --export mcps/production.yaml --no-auth-prompt
git add mcps/production.yaml
git commit -m "docs: update production MCP config"
```

Pro tip: Always use `--no-auth-prompt` for files going into version control.
{% endstep %}

{% step %}

### Backup & Disaster Recovery

```bash
# Backup all MCPs
for mcp_id in $(aip mcps list --view json | jq -r '.[].id'); do
  aip mcps get "$mcp_id" --export "backups/mcp-${mcp_id}.json" --no-auth-prompt
done
```

{% endstep %}

{% step %}

### Environment Migration

```bash
# Export from staging
aip mcps get staging-mcp --export mcp-config.yaml --no-auth-prompt

# Manually add secrets to the exported file

# Then import to production (implementation depends on your setup)
```

{% endstep %}

{% step %}

### Documentation Generation

```bash
# Create sanitized config for team documentation
aip mcps get team-mcp \
  --export docs/mcp-setup.yaml \
  --no-auth-prompt \
  --auth-placeholder "See team secrets vault"
```

{% endstep %}
{% endstepper %}

## Security Best Practices

1. Never commit actual secrets to version control
   * Always use `--no-auth-prompt` for files going into Git
   * Use placeholders and inject secrets at deployment time
2. Interactive mode caution
   * Be careful when entering actual secrets in interactive mode
   * Consider if the exported file will be shared or committed
3. Placeholder strategy
   * Use descriptive placeholders that guide users to the right secret source
   * Examples: `${ENV_VAR}`, `VAULT:path/to/secret`, `SEE_DOCS`
4. Secret injection
   * Use environment variables or secret managers in CI/CD
   * Replace placeholders programmatically before deployment

## Troubleshooting

<details>

<summary>Command hangs in CI/CD</summary>

**Problem:** Command waits indefinitely for input in non-interactive environment.

**Solution:** Add `--no-auth-prompt` flag:

```bash
aip mcps get $MCP_ID --export config.json --no-auth-prompt
```

</details>

<details>

<summary>Warning: Non-interactive mode detected</summary>

This is informational — the CLI detected it's not running in a terminal and automatically used placeholders.

</details>

<details>

<summary>Exported file missing authentication</summary>

If no authentication is configured on the MCP, the `authentication` field will be omitted from the export (as expected).

</details>

## Related Documentation

* [MCP Schema Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/schemas/model-context-protocol-mcp) — Field specifications
* [REST API: MCPs](https://gdplabs.gitbook.io/gl-aip/resources/reference/rest-api/model-context-protocol-mcp) — API endpoints
* [Python SDK Reference](https://gdplabs.gitbook.io/gl-aip/resources/reference/python-sdk-reference#model-context-protocol-mcp) — SDK usage