Skip to main content

AWS Security Agent MCP Server

License: Apache-2.0 Python 3.11+

An AWS Labs Model Context Protocol (MCP) server for AWS Security Agent — automated security scanning and penetration testing.

This MCP server provides full access to the AWS Security Agent service, enabling developers to scan source code for vulnerabilities, run penetration tests against live applications, manage integrations, and apply auto-generated fixes — all from any MCP-compatible client.

Features

  • Code security scanning — zip, upload, scan source code, get findings with fixes
  • Penetration testing — test live applications via target domains
  • Full API access — call_api tool exposes all SecurityAgent operations
  • Auto-provisioning — creates agent space and IAM service role on first use
  • Respects .gitignore — excludes ignored files from packaging

Prerequisites

  1. uv installed
  2. Python 3.11+ (uv python install 3.11)
  3. AWS credentials configured (via aws configure, SSO, or environment variables)

Installation

{
  "mcpServers": {
    "awslabs.security-agent-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.security-agent-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "awslabs.security-agent-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AWS_REGION=us-east-1",
        "-e", "AWS_ACCESS_KEY_ID",
        "-e", "AWS_SECRET_ACCESS_KEY",
        "-e", "AWS_SESSION_TOKEN",
        "awslabs/security-agent-mcp-server:latest"
      ]
    }
  }
}

Environment Variables

Variable Description Default
AWS_REGION AWS region for SecurityAgent API calls us-east-1
AWS_PROFILE AWS credential profile name default profile
FASTMCP_LOG_LEVEL Log level (DEBUG, INFO, WARNING, ERROR) WARNING

Available Regions

See AWS documentation for available regions.

Available Tools

Setup

Tool Description
setup_check Verify prerequisites — credentials, agent space, role
setup Create/reuse agent space and IAM service role

Code Review (orchestrated)

Tool Description
start_security_scan Zip code, upload to S3, create review, start scan. Returns scan_id.
get_scan_status Poll scan progress
get_scan_findings Get findings from completed scan
list_scans List tracked scans
stop_scan Cancel a running scan

Remediation

Tool Description

Full API Access

Tool Description
call_api Call any SecurityAgent API operation (pentests, target domains, integrations, artifacts, etc.)
get_api_guide List all available operations dynamically + documentation link

Usage Flows

Code Review (source scan)

1. setup_check()              → verify readiness
2. setup()                    → provision resources (one-time)
3. start_security_scan(path=".")
4. get_scan_status()          → poll until COMPLETED
5. get_scan_findings()        → retrieve findings

Penetration Test

1. setup_check() → setup()   → one-time
2. call_api("CreateTargetDomain", {targetDomainName, verificationMethod})
3. call_api("VerifyTargetDomain", {targetDomainId})
4. call_api("CreatePentest", {agentSpaceId, title, assets: {endpoints: [...]}, serviceRole})
5. call_api("StartPentestJob", {agentSpaceId, pentestId})
6. Poll: call_api("BatchGetPentestJobs", {agentSpaceId, pentestJobIds})
7. call_api("ListFindings", {agentSpaceId, pentestJobId})

Any Operation

1. get_api_guide()            → see all operations + docs link
2. call_api(operation, params) → execute

Required IAM Permissions

These permissions are needed on your AWS credentials (the identity running the MCP server):

For setup (one-time)

  • iam:CreateRole, iam:PutRolePolicy (if creating a new service role)
  • s3:CreateBucket, s3:PutPublicAccessBlock, s3:PutLifecycleConfiguration (if creating a new bucket)
  • sts:GetCallerIdentity
  • securityagent:CreateAgentSpace, securityagent:UpdateAgentSpace
  • securityagent:ListAgentSpaces, securityagent:BatchGetAgentSpaces

For code scanning

  • s3:PutObject
  • securityagent:CreateCodeReview, securityagent:StartCodeReviewJob
  • securityagent:BatchGetCodeReviewJobs, securityagent:StopCodeReviewJob
  • securityagent:ListFindings, securityagent:BatchGetFindings
  • securityagent:StartCodeRemediation, securityagent:BatchDeleteCodeReviews

For pentesting and other operations

Add SecurityAgent permissions as needed for your use case. See How AWS Security Agent works with IAM for details on available actions.

Service Role

During setup, the server creates an IAM service role SecurityAgentScanRole (if one doesn't already exist). If an existing role is found on the agent space, it can be reused after validating its permissions.

The service role is assumed by the SecurityAgent service to read your uploaded code:

  • Trust policy: securityagent.amazonaws.com service principal
  • Permissions: S3 read on scan bucket, CloudWatch Logs write

Note: An S3 bucket is used to temporarily store source code for scanning. The MCP server sets a 30-day lifecycle policy on buckets it creates — uploaded content is automatically deleted. If you use your own bucket, consider adding a lifecycle rule to manage storage costs.

Contributing

Contributions are welcome! Please see the main repository's CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Metadata

Release files for awslabs.security-agent-mcp-server 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for awslabs.security-agent-mcp-server 0.2.3
File Size Uploaded Provenance Actions
awslabs_security_agent_mcp_server-0.2.3.tar.gz 144.8 kB With provenance Details for awslabs_security_agent_mcp_server-0.2.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for awslabs.security-agent-mcp-server 0.2.3
File Interpreter ABI Platform Actions
awslabs_security_agent_mcp_server-0.2.3-py3-none-any.whl Python 3 none any Details for awslabs_security_agent_mcp_server-0.2.3-py3-none-any.whl

Total release size: 177.8 kB

Release files / awslabs_security_agent_mcp_server-0.2.3.tar.gz

Download URL awslabs_security_agent_mcp_server-0.2.3.tar.gz
Size 144.8 kB
Tags Source
SHA-256 checksum
How to use checksums
611fa6dfe247e9cfb3b2b0776e1ef3fae7e0c43905b5c168791463db8b6c8bcd
BLAKE2b-256 checksum
How to use checksums
78a8c68b117c755527de573c7fa2ca16f58ea5cf124e2b2e5db5bf7e9a62e029
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / awslabs_security_agent_mcp_server-0.2.3-py3-none-any.whl

Download URL awslabs_security_agent_mcp_server-0.2.3-py3-none-any.whl
Size 33.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
99b6e0942fc5ba149d4f45c8b3d47626a03fc89b46ff913893f74653e5fc9b11
BLAKE2b-256 checksum
How to use checksums
83778886f4d11e3a343f3e34aa08b49b5f49717254b72cd4654a84fc19491157
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for awslabs.security-agent-mcp-server 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for awslabs_security_agent_mcp_server-0.2.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page