http-mcp-headers

---
name: http-mcp-headers
description: Implement secret-safe HTTP headers for MCP transport in gh-aw.
---


# HTTP MCP Header Secret Support - Implementation Summary

Use this reference for HTTP MCP header secret support in the copilot engine.

## Problem Statement

When HTTP MCP headers include GitHub Actions secrets, `mcp-config.json` must:

1. Extract secrets from headers (e.g., `${{ secrets.DD_API_KEY }}`)
2. Declare those env variables in the execution step
3. Configure the MCP config's "env" section to passthrough those variables
4. Use the passed variables in the headers section

## Example Workflow

```markdown
on:
  workflow_dispatch:
permissions:
  contents: read
engine: copilot
mcp-servers:
  datadog:
    type: http
    url: "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp"
    headers:
      DD_API_KEY: "${{ secrets.DD_API_KEY }}"
      DD_APPLICATION_KEY: "${{ secrets.DD_APPLICATION_KEY }}"
      DD_SITE: "${{ secrets.DD_SITE || 'datadoghq.com' }}"
    allowed:
      - search_datadog_dashboards
      - search_datadog_slos
      - search_datadog_metrics
      - get_datadog_metric

# Datadog Dashboard Search

Search for Datadog dashboards and provide a summary.
```

## Generated Output

### 1. MCP Config (mcp-config.json)

```json
{
  "mcpServers": {
    "datadog": {
      "type": "http",
      "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp",
      "headers": {
        "DD_API_KEY": "${DD_API_KEY}",
        "DD_APPLICATION_KEY": "${DD_APPLICATION_KEY}",
        "DD_SITE": "${DD_SITE}"
      },
      "tools": [
        "search_datadog_dashboards",
        "search_datadog_slos",
        "search_datadog_metrics",
        "get_datadog_metric"
      ],
      "env": {
        "DD_API_KEY": "\\${DD_API_KEY}",
        "DD_APPLICATION_KEY": "\\${DD_APPLICATION_KEY}",
        "DD_SITE": "\\${DD_SITE}"
      }
    }
  }
}
```

### 2. Execution Step Environment Variables

```yaml
env:
  DD_API_KEY: ${{ secrets.DD_API_KEY }}
  DD_APPLICATION_KEY: ${{ secrets.DD_APPLICATION_KEY }}
  DD_SITE: ${{ secrets.DD_SITE || 'datadoghq.com' }}
  COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
  # ... other env vars
```

`GH_AW_MCP_CONFIG` is intentionally NOT in the YAML `env:` block — it is exported from the run script (`export GH_AW_MCP_CONFIG="$HOME/.copilot/mcp-config.json"`) so `$HOME` is resolved at runtime. GitHub Actions does not shell-expand `env:` values, so the path must be set via `export` to work on self-hosted/containerized runners where `HOME` is not `/home/runner`.

## Implementation Details

### Key Functions

1. **extractSecretsFromValue(value string)** - Extracts secret expressions from a string
   - Parses `${{ secrets.VAR_NAME }}` patterns
   - Handles default values: `${{ secrets.VAR || 'default' }}`
   - Returns map of variable names to full expressions

2. **extractSecretsFromHeaders(headers map[string]string)** - Extracts all secrets from HTTP headers
   - Iterates through all header values
   - Collects all unique secret expressions
   - Returns consolidated map of secrets

3. **replaceSecretsWithEnvVars(value string, secrets map[string]string)** - Replaces secret expressions with env var references
   - Transforms `${{ secrets.DD_API_KEY }}` to `${DD_API_KEY}`
   - Used in MCP config headers rendering

4. **collectHTTPMCPHeaderSecrets(tools map[string]any)** - Collects secrets from all HTTP MCP tools
   - Scans all tools for HTTP MCP configurations
   - Extracts secrets from each tool's headers
   - Returns consolidated map for execution step env

### Rendering Logic

#### In renderSharedMCPConfig (mcp-config.go):

1. **Extract secrets** when rendering HTTP MCP configs for copilot engine
2. **Add env section** to property order when secrets are found
3. **Render headers** with env var references instead of secret expressions
4. **Render env** with passthrough syntax (`\${VAR_NAME}`)

#### In GetExecutionSteps (copilot_engine.go):

1. **Collect all HTTP MCP header secrets** from workflow tools
2. **Add to execution step env map** with secret expressions

## Security Benefits

1. **Secrets never appear in MCP config** - Only env var references
2. **Proper GitHub Actions secret handling** - Uses `${{ secrets.* }}` syntax
3. **Environment isolation** - Each MCP server receives only its required secrets
4. **Consistent pattern** - Matches existing GitHub remote MCP server implementation

## Test Coverage

### Unit Tests (mcp_http_headers_test.go)
- extractSecretsFromValue
- extractSecretsFromHeaders
- replaceSecretsWithEnvVars
- collectHTTPMCPHeaderSecrets
- renderSharedMCPConfig with HTTP headers

### Integration Tests (copilot_mcp_http_integration_test.go)
- Single HTTP MCP tool with secrets
- Multiple HTTP MCP tools
- HTTP MCP without secrets
- Property ordering
- Env variable sorting

All tests pass ✓