AWS MCP Server

# Troubleshooting Common issues and fixes when using the AWS MCP server. --- ## Credential failures ### "Could not load credentials" - **Cause:** AWS credentials are not configured. - **Fix:** 1. Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your environment or MCP client config. 2. Or use `AWS_PROFILE` pointing to a profile in `~/.aws/credentials`. 3. Or run `aws sso login` if using SSO (see [SSO_AND_CROSS_ACCOUNT.md](SSO_AND_CROSS_ACCOUNT.md)). ### "Access Denied" or "UnauthorizedOperation" - **Cause:** IAM user/role lacks the permissions required by the tool. - **Fix:** 1. Use `get_iam_policy_for_tools` to generate the least-privilege policy for the tools you use. 2. Attach that policy to the IAM user or role used by the MCP server. 3. See [IAM_PERMISSIONS.md](IAM_PERMISSIONS.md) for per-tool permissions. ### SSO session expired - **Cause:** `aws sso login` session has expired. - **Fix:** Run `aws sso login` again and restart the MCP client. --- ## Throttling ### "Rate exceeded" or "TooManyRequestsException" - **Cause:** AWS API rate limits were exceeded. - **Fix:** 1. The server uses exponential backoff—retries should succeed after a short wait. 2. Enable caching: set `MCP_AWS_CACHE_TTL=60` (seconds) to reduce repeated calls. 3. Reduce concurrent tool usage or add rate limiting via `mcp-config.json` (`rateLimitPerMinute`). --- ## Region / permissions ### "The security token included in the request is invalid" - **Cause:** Credentials are expired or malformed. - **Fix:** Refresh credentials (e.g. re-run `aws sso login`) and verify env vars are correct. ### "Requested resource not found" or empty results - **Cause:** Resource may exist in another region, or the account has no resources. - **Fix:** Pass the `region` argument to tools that support it (e.g. `list_ec2_instances`, `list_rds_instances`, `list_lambda_functions`). --- ## LocalStack ### "Could not connect to the endpoint" (LocalStack) - **Cause:** LocalStack is not running or the endpoint URL is wrong. - **Fix:** 1. Start LocalStack: `docker run -d -p 4566:4566 localstack/localstack` 2. Set `AWS_ENDPOINT_URL=http://localhost:4566` in the MCP client env. 3. Use `MCP_AWS_DRY_RUN=true` for testing without any AWS/LocalStack. --- ## MCP client issues ### Server doesn't start or crashes immediately - **Cause:** Wrong Node path or missing build. - **Fix:** 1. Run `npm run build` in the project root. 2. Use the **absolute path** to `dist/index.js` in your MCP client config. 3. Ensure Node.js 18+ is installed (`node -v`). ### "Unknown tool" when calling a tool - **Cause:** Typo in tool name or an older server version. - **Fix:** Check [TOOLS.md](TOOLS.md) for correct tool names and parameters. --- ## Dry-run and testing - Set `MCP_AWS_DRY_RUN=true` to return mock data without calling AWS—useful for testing the MCP integration. - Use `npm run cli -- get_aws_caller_identity` (or `aws_health_check`) to test locally.