# Sample Mcp Workflow Orchestrator For Agentcore > Reference architecture for building multi-MCP-server systems on Amazon Bedrock AgentCore — explainable planner, pluggable YAML registry, cross-server evidence correlation. Swap in any MCP servers; the orchestration pattern stays the same. - **Type:** MCP server - **Install:** `agentstack add mcp-aws-samples-sample-mcp-workflow-orchestrator-for-agentcore` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [aws-samples](https://agentstack.voostack.com/s/aws-samples) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT-0 - **Upstream author:** [aws-samples](https://github.com/aws-samples) - **Source:** https://github.com/aws-samples/sample-mcp-workflow-orchestrator-for-agentcore - **Website:** https://aws.amazon.com/bedrock/agentcore/ ## Install ```sh agentstack add mcp-aws-samples-sample-mcp-workflow-orchestrator-for-agentcore ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # AWS MCP Workflow Orchestrator > As MCP server catalogs grow, the hard problem shifts from building individual tools to **coordinating them intelligently**. This orchestrator solves that — it's the reasoning layer that decides which servers to call, when, and how to stitch their outputs into one coherent answer. A **reference architecture for building multi-MCP-server systems** on Amazon Bedrock AgentCore. Instead of connecting to one server at a time, it shows how to plan multi-step investigations across multiple servers, execute them through a single Gateway connection, correlate cross-server evidence, and produce a cited answer — all while recording **why** each decision was made in an auditable log. The six AWS MCP servers included (CloudWatch, CloudTrail, IAM, Pricing, Documentation, AWS MCP Server) are just one configuration. **The architecture is the value, not the specific servers.** Swap them for any combination of MCP servers — internal tools, third-party APIs, domain-specific services — and the orchestration pattern works the same. The planner adapts automatically from the YAML registry; no code changes needed. **Use this as a blueprint** for building any multi-MCP-server system where you need explainable coordination, pluggable server discovery, and cross-server evidence correlation. [](LICENSE) [](https://www.python.org/) > ⚠️ **Disclaimer**: This project is provided as sample/educational code and is NOT intended for production use without additional security hardening. See [SECURITY.md](SECURITY.md) for production recommendations. --- ## When to Use This Use this project when you need to: - **Build a multi-MCP-server architecture** — you want a proven pattern for coordinating 2+ MCP servers behind a single gateway with a planner that routes intelligently - **Adapt it to your own domain** — replace the AWS MCP servers with your own (databases, internal APIs, SaaS tools) by dropping YAML manifests and Dockerfiles — the orchestration logic stays the same - **Understand multi-server orchestration** — you want to learn how an AI agent decides which MCP servers to call, in what order, and how to combine their outputs - **Audit agent reasoning** — you need a human-readable decision log that records *why* each tool was chosen (explainability, compliance, debugging) - **Build on top of AgentCore** — you want a reference pattern showing how to integrate AgentCore Gateway, Lambda-hosted MCP servers, and Bedrock reasoning in one architecture ## When NOT to Use This - **You just need one MCP server** — if your use case involves a single server (e.g., only CloudWatch), connect it directly to your agent. No orchestration layer needed. - **You want a production-ready managed solution** — use [AWS DevOps Agent](https://aws.amazon.com/devops-agent/) (GA) or [AWS MCP Server Agent SOPs](https://docs.aws.amazon.com/aws-mcp/latest/userguide/what-is-mcp-server.html) instead. They're battle-tested, fully managed, and require no infrastructure maintenance. - **You don't need explainability** — if you don't care *why* the agent chose a particular tool and just want the answer, managed black-box solutions are simpler and faster to adopt. - **You need multi-turn planning** — this orchestrator currently runs a single-pass plan. If your workflow requires chaining outputs (step N feeds into step N+1), you'll need to extend it or wait for that feature. --- ## Why This Exists AWS has dozens of MCP servers — CloudWatch, CloudTrail, IAM, Pricing, Documentation — each exposing tools for a specific domain. But when you ask a cross-cutting question like *"My ECS service returns 503s — what happened?"*, no single server has the full answer. You need to: 1. Check CloudWatch for error metrics and logs 2. Check CloudTrail for what was deployed and when 3. Check IAM for any permission changes 4. Cross-reference all of that to find the root cause 5. Look up best practices for the fix **Today, this orchestration happens manually.** AWS's managed solutions (DevOps Agent, AWS MCP Server SOPs) do this as a black box — you can't see or modify the reasoning. **This repo is the open, explainable alternative.** A reference architecture that shows how to build a multi-MCP-server system with an AI planner that reasons across servers, records every decision, and lets you swap or add servers without changing code. The AWS servers are the demo — the pattern applies to any MCP servers. --- ## What It Does ``` You: "Someone changed IAM policies last night. Check who, what alarms fired, and give me security recommendations." Orchestrator: Step 1 → iam-mcp / list_policies (found 3 customer policies) Step 2 → cloudtrail-mcp / lookup_events (found AssumeRole + policy changes) Step 3 → cloudwatch-mcp / get_active_alarms (no alarms firing) Step 4 → documentation-mcp / search_documentation (S3 security best practices) Step 5 → Correlate evidence from 4 servers Step 6 → Synthesize answer with citations Answer: "Your account has 3 customer policies. CloudTrail shows AssumeRole events from... No alarms are firing. Recommended: enable CloudTrail metric filters for IAM changes..." [Sources: iam-mcp, cloudtrail-mcp, cloudwatch-mcp, documentation-mcp] ``` --- ## Key Features - **Multi-server orchestration** — 6 MCP servers, 14 tools, all coordinated by a single planner - **Explainable planning** — every step records *why* a server was chosen (decision log you can audit) - **Pluggable registry** — add a server by dropping a YAML manifest; the planner adapts automatically - **Evidence correlation** — merges outputs across servers, attributes sources - **Hosted on AWS** — Lambda functions behind AgentCore Gateway, all IAM auth, no OAuth - **One-command deploy** — `./scripts/deploy_lambda_servers.sh` creates everything from zero --- ## Architecture ``` Your machine (CLI) │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ Orchestrator (this repo) │ │ ┌─────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐ │ │ │ Planner │→ │ Registry │→ │ Gateway │→ │ Correlate│ │ │ │(Bedrock)│ │ (YAML) │ │ Client │ │ Engine │ │ │ └─────────┘ └──────────┘ └─────────────┘ └──────────┘ │ └──────────────────────┬───────────────────────────────────────┘ │ ┌──────────────┼──────────────────────────┐ │ │ │ ▼ ▼ ▼ AgentCore Gateway AWS MCP Server (direct session) │ (managed remote) ├── Lambda: cloudwatch-mcp ├── Lambda: cloudtrail-mcp ├── Lambda: iam-mcp ├── Lambda: pricing-mcp └── Lambda: documentation-mcp ``` See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full write-up. --- ## Quickstart ### Prerequisites - Python 3.11+ - AWS CLI v2 with configured credentials - [Finch](https://github.com/runfinch/finch) (or Docker) for container builds - An AWS account with Bedrock + AgentCore access in `us-east-1` ### Deploy ```bash git clone https://github.com//aws-mcp-workflow-orchestrator cd aws-mcp-workflow-orchestrator # Deploy all infrastructure (Lambda, ECR, Gateway, IAM roles) ./scripts/deploy_lambda_servers.sh --region us-east-1 # Copy the output into .env cp .env.example .env # Edit .env with the AGENTCORE_GATEWAY_URL from deploy output ``` ### Install & Run ```bash python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # Run the orchestrator python -m orchestrator.cli "What are my CloudWatch alarms in us-east-1?" ``` ### Test All Tools ```bash python scripts/test_all_tools.py ``` ### Tear Down ```bash ./scripts/destroy_lambda_servers.sh --region us-east-1 ``` --- ## Adding a New MCP Server This is the core value proposition — **adding a server is a config change, not a code change.** ### Step 1: Create a YAML manifest ```yaml # mcp_registry/s3.yaml server: s3-mcp gateway_target: s3-mcp domains: [storage, security, data] provides: - capability: list_buckets good_for: "listing S3 buckets and their configurations" - capability: get_bucket_policy good_for: "checking bucket policies for public access or misconfigurations" preconditions: [region] ``` ### Step 2: Create a Dockerfile ```dockerfile # lambda/Dockerfile.s3 FROM public.ecr.aws/lambda/python:3.12 RUN pip install --no-cache-dir awslabs.mcp-lambda-handler awslabs.s3-mcp-server ENV MCP_SERVER_COMMAND="awslabs.s3-mcp-server" ENV MCP_TIMEOUT="90" COPY handler.py ${LAMBDA_TASK_ROOT}/ CMD ["handler.lambda_handler"] ``` ### Step 3: Add to the deploy script Add your server to the `SERVERS` list and `add_target` call in `scripts/deploy_lambda_servers.sh`, then redeploy. ### Step 4: Done The planner automatically includes the new server in its reasoning next time it runs. No planner code changes needed. --- ## Repository Layout ``` orchestrator/ Core Python package planner.py Explainable planner (plan → act → observe → correlate → decide) registry.py Loads YAML manifests, presents capability catalog gateway_client.py MCP client (Gateway + direct AWS MCP Server) correlation.py Evidence correlation engine decision_log.py Structured reasoning trace config.py Settings from .env cli.py CLI entrypoint lambda/ Lambda container images handler.py Generic handler (spawns MCP server subprocess) Dockerfile.* One per MCP server mcp_registry/ Pluggable server manifests (the extensibility contract) aws_mcp_server.yaml cloudwatch.yaml cloudtrail.yaml iam.yaml pricing.yaml well_architected.yaml scripts/ Infrastructure automation deploy_lambda_servers.sh One-command full deployment destroy_lambda_servers.sh One-command teardown test_all_tools.py Validates all 14 tools scenarios/ Example prompts and expected reasoning tests/ Unit tests (no AWS credentials needed) docs/ Architecture documentation ``` --- ## How It Works See [`docs/HOW_IT_WORKS.md`](docs/HOW_IT_WORKS.md) for the detailed flow. --- ## Limitations | Limitation | Detail | Workaround | |-----------|--------|------------| | **Pricing queries require filters** | The AWS Pricing API returns 300K+ chars for unfiltered queries; the server returns a "use more specific filters" suggestion | Pass `service_code` + `filters` + `max_results` for targeted results | | **Single-pass planner** | The planner can't use output from step N as input to step N+1 in the same run (e.g., get a policy ARN then read it) | Run again with the specific ARN, or implement multi-turn planning | | **Lambda cold starts** | First invocation of each Lambda takes 5-15s (container image startup) | Subsequent calls are fast; use provisioned concurrency for production | | **aws-mcp-server auth** | The managed AWS MCP Server's `call_aws`/`run_script` tools require OAuth (session-based auth for write operations) | Use `search_documentation`/`read_documentation` (work without auth); Lambda targets handle all AWS API calls via IAM | | **Stdio MCP server buffering** | Some MCP servers (async/FastMCP-based) may have output buffering issues in Lambda's subprocess model | The handler uses threading + stdin close to force output; works for all tested servers | --- ## Contributing Issues and PRs welcome — especially: - New server manifests under `mcp_registry/` - New Dockerfiles under `lambda/` - Planner prompt improvements - Multi-turn planning support See [`CONTRIBUTING.md`](CONTRIBUTING.md). --- ## License MIT-0. See [`LICENSE`](LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [aws-samples](https://github.com/aws-samples) - **Source:** [aws-samples/sample-mcp-workflow-orchestrator-for-agentcore](https://github.com/aws-samples/sample-mcp-workflow-orchestrator-for-agentcore) - **License:** MIT-0 - **Homepage:** https://aws.amazon.com/bedrock/agentcore/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-aws-samples-sample-mcp-workflow-orchestrator-for-agentcore - Seller: https://agentstack.voostack.com/s/aws-samples - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.