# Configuration
The MCP server can be configured via environment variables and an optional `mcp-config.json` file.
---
## Environment variables
| Variable | Description | Default |
|----------|-------------|---------|
| `AWS_ACCESS_KEY_ID` | AWS access key | — |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key | — |
| `AWS_REGION` | Default AWS region | `us-east-1` |
| `AWS_PROFILE` | Named profile from `~/.aws/credentials` | — |
| `AWS_ENDPOINT_URL` | Custom endpoint (e.g. LocalStack: `http://localhost:4566`) | — |
| `MCP_AWS_DRY_RUN` | Return mock data, no AWS calls | `false` |
| `MCP_AWS_AUDIT_LOG` | Log tool invocations for compliance | `false` |
| `MCP_AWS_CACHE_TTL` | Cache TTL in seconds (0 = disabled) | `60` |
| `MCP_AWS_RATE_LIMIT` | Max tool calls per minute (0 = disabled) | `0` |
| `MCP_AWS_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` | `info` |
---
## mcp-config.json
Create `mcp-config.json` in the project root (next to `package.json`). Copy from `mcp-config.json.example`.
### Schema
```json
{
"enabledTools": null,
"defaults": {},
"webhookUrl": null,
"webhookSecret": null,
"rateLimitPerMinute": 120,
"assumeRole": null
}
```
### Options
| Field | Type | Description |
|-------|------|-------------|
| `enabledTools` | `string[] \| null` | If set, only these tool names are allowed. `null` = all tools. |
| `defaults` | `Record<string, Record<string, unknown>>` | Default argument values per tool. Example: `{"list_iam_users": {"max_results": 50}}` |
| `webhookUrl` | `string \| null` | URL to POST tool invocation events (success/failure). |
| `webhookSecret` | `string \| null` | Optional secret for webhook signature. |
| `rateLimitPerMinute` | `number` | Max tool calls per minute. Overrides `MCP_AWS_RATE_LIMIT` if set. |
| `assumeRole` | `object \| null` | Role ARN to assume. See [SSO_AND_CROSS_ACCOUNT.md](SSO_AND_CROSS_ACCOUNT.md). |
### Example
```json
{
"defaults": {
"list_iam_users": { "max_results": 50 },
"list_s3_buckets": { "check_public_access": true }
},
"rateLimitPerMinute": 120,
"webhookUrl": "https://your-app.com/webhooks/mcp",
"webhookSecret": "your-secret"
}
```
---
## Loading order
1. Environment variables
2. `mcp-config.json` (if present)
3. Config file values override env where applicable (e.g. `rateLimitPerMinute`)
