AWS Builder Center

Build and test an MCP capacity calculator: missing inputs, explicit assumptions and AWS hosting

Run a local MCP capacity calculator, inspect how it preserves missing inputs and labels assumptions, and test real protocol responses over stdio and HTTP. Includes code, a reproducible lab and the existing AWS hosting boundary.

Senior Solutions Architect at Banco Itaú | Cloud, event-driven, AI agents & FinOps
A product team gives you one requirement: its order API must handle a peak of 500 requests per second. You are building an architecture assistant that can call tools, and you want it to help with an initial capacity discussion. Before it recommends resources, what can it actually calculate from that one number?
Not concurrency. For this simplified exercise, concurrency means requests being processed at the same time, estimated as arrival rate multiplied by processing duration. If we hypothesize a duration of 250 milliseconds, the calculation is 500 × 0.250 = 125 concurrent requests. Adding 30 percent headroom gives 163 after rounding up. These are scenario calculations; the team has not supplied that duration, so 163 is not an approved production capacity requirement.
This tutorial is for developers building MCP tools for architecture assistants. MCP lets a client discover and call a server's tools. We will use one small deterministic tool,  capacity_plan , to learn how its input schema and response can keep missing information visible. You will run the published implementation, inspect the code changes behind it, and test the real MCP responses. You will not build an autonomous architect, run an LLM evaluation, select AWS instance sizes or deploy new AWS infrastructure.
The implementation lives in my open-source Moretes Architect MCP workbench, version 0.5.0. That workbench contains other tools, but this article follows only  capacity_plan  and its validation handler. Its existing public deployment uses API Gateway, Lambda and an operational DynamoDB table. The main exercise runs locally, without AWS credentials or a language model; the final section explains how this same tool fits into the existing AWS hosting boundary.
The practical problem came from a first-use report by Pin Xiong in the workbench's GitHub issue #19. A client called the earlier tool with incomplete inputs and received a rejection. When a caller subsequently supplied hypothetical values, the response did not clearly separate those from supplied requirements. That report motivated the 0.5.0 implementation examined here. It is evidence about this tool's behavior, not a claim that all assistants invent inputs or that the fix eliminates hallucinations.

What you will build and verify

By the end, you will distinguish three outcomes:
  1. A syntactically invalid request: return a tool error with the fields to fix.
  1. A valid but incomplete scenario: return useful partial results and explicit unknowns.
  1. A complete scenario containing assumptions: calculate, but retain their origin and do not call the workload validated.
The working result is a terminal-based MCP client and an acceptance test you can rerun. First send only the known peak rate and expect null concurrency plus a list of missing fields. Then add explicitly hypothetical inputs and expect 125/163, still labeled unvalidated. Finally, test invalid input and repeat the checks over local HTTP. The code excerpts explain how to implement this behavior in your own tool; installing this package alone does not implement your broader architecture workflow.
You need Node.js 22.13 or newer, npm and a terminal. Package installation needs network access. The local calculations require no AWS credentials or paid model. An IDE using its own model has its own usage and billing; this exercise does not test that model's behavior.

1. Reproduce the incomplete request first

Use the pinned package and explicit CLI binary:
npx --yes --package moretes-aws-architect-mcp@0.5.0 \
moretes-architect call capacity_plan \
--arg requestsPerSecond=500 --arg rateType=peak \
--arg 'inputProvenance={"requestsPerSecond":"provided"}'
The important fields are:
{
"validated": false,
"status": "insufficient-inputs",
"insufficientInputs": ["durationMs", "payloadKB"],
"averageConcurrency": null,
"plannedConcurrency": null,
"dailyRequests": null,
"dailyPayloadGB": null
}
This is a successful tool call with an incomplete business scenario, not a failed transport. The client can ask for the missing data. Do not convert null to zero, or let an output formatter quietly omit it.
The explicit  rateType=peak  matters. Five hundred peak requests per second does not establish a daily volume. The compatibility default  unspecified  still returns a conditional sustained-rate scenario; it is not a traffic forecast. Set the rate type rather than relying on that default.

2. Change the input contract, not just the instruction prompt

Making every number mandatory encourages callers to fill a form even when the evidence does not exist. Keep the traffic rate required, but let the dependent inputs remain absent:
const shape = {
requestsPerSecond: z.number().nonnegative().max(1e9),
durationMs: z.number().nonnegative().max(86400000).optional(),
payloadKB: z.number().nonnegative().max(1e9).optional(),
headroom: z.number().min(1).max(10).optional(),
rateType: z.enum(['peak', 'sustained', 'unspecified'])
.default('unspecified')
};
This excerpt belongs inside the existing tool registration, not a standalone server. The full  implementation  also declares the strict per-field provenance object. Read it when adapting the code; copying only a calculator body would omit validation and protocol handling.
Export the schema in Zod's input mode:
z.toJSONSchema(schema, { io: 'input' });
Input and output are different contracts when defaults are involved. In this implementation, exporting the wrong mode made defaulted fields look mandatory in discovery. Verify the actual  tools/list  schema:  capacity_plan.required  should contain only  requestsPerSecond .

3. Calculate only what the available data supports

The core arithmetic can stay small:
const headroom = a.headroom ?? 1.3;
const concurrency = a.durationMs === undefined
? null : a.requestsPerSecond * a.durationMs / 1000;
const dailyRequests = a.rateType === 'peak'
? null : a.requestsPerSecond * 86400;
const dailyPayloadGB = dailyRequests === null || a.payloadKB === undefined
? null : dailyRequests * a.payloadKB / 1e6;
Missing duration blocks concurrency. Missing payload blocks payload volume, but does not block concurrency if duration is present. A peak rate blocks daily extrapolation. Zero is a supplied number; an undefined value is missing. Use explicit undefined checks and nullish coalescing rather than truthiness tests.
These outputs describe a scenario under stated assumptions. They do not determine a Lambda concurrency reservation, database connection pool, instance size or service quota. Tail latency, retries, batching, downstream saturation and request distributions still need workload evidence. The retained field name  averageConcurrency  is not a measurement; for a peak-rate input it is arithmetic under that selected arrival-rate scenario.

4. Keep assumptions attached to individual values

Now supply a hypothetical duration and payload, labeling them honestly:
npx --yes --package moretes-aws-architect-mcp@0.5.0 \
moretes-architect call capacity_plan \
--arg requestsPerSecond=500 --arg durationMs=250 \
--arg payloadKB=4 --arg headroom=1.3 --arg rateType=peak \
--arg 'inputProvenance={"requestsPerSecond":"provided","durationMs":"assumed","payloadKB":"assumed","headroom":"assumed"}'
The calculation is  500 × 0.250 = 125 ; applying headroom gives  ceil(125 × 1.3) = 163 . Those are calculated scenario values, not benchmark results. Daily volume remains null because the rate is a peak.
The response retains origin beside value:
{
"requestsPerSecond": { "value": 500, "origin": "provided" },
"durationMs": { "value": 250, "origin": "assumed" },
"payloadKB": { "value": 4, "origin": "assumed" },
"headroom": { "value": 1.3, "origin": "assumed" }
}
That is a projection of the  provenance  object, not the entire result. If headroom is omitted, its origin is  server-default . An unlabeled supplied number becomes  caller-unspecified . A label attached to an absent value does not make that value exist.
The distinction is useful but deliberately limited: the caller can falsely label a guess  measured . The server does not verify a measurement or establish approval by the workload owner. A production workflow needs a separate reviewed evidence record, measurement date and accountable owner. Keeping  validated: false  avoids turning arithmetic into an endorsement.

5. Make invalid input actionable for the client

Business incompleteness and invalid syntax should not share one opaque error string. A missing required rate produces:
{
"isError": true,
"structuredContent": {
"kind": "input-validation-error",
"validated": false,
"missing": ["requestsPerSecond"],
"issues": [{ "path": ["requestsPerSecond"], "code": "invalid_type" }]
}
}
This is a projection of the MCP result; the response also includes human-readable text. For a negative supplied rate,  missing  is empty and  issues  identifies the invalid field. Nested paths can identify missing item fields without parsing English prose.
The  MCP tool specification  defines structured tool results and output schemas. Structured server content is not a guarantee about a client's generated explanation. In this server, the SDK's actual discovery and call results are tested, including error handling. Structured error data includes paths and codes, not the supplied values; paths can still reveal field names, so use synthetic inputs on a public service.

6. Test the published package through MCP, not just a function

Download the  companion lab ZIP , extract it into a new disposable directory, and locate its  lab/  folder. It contains pinned dependencies and  acceptance.test.mjs . Run:
cd lab
npm ci --ignore-scripts --no-fund --no-audit
npm test
The test launches the published server over stdio with account tools explicitly disabled, initializes a real MCP SDK client and checks six scenarios:
Scenario
Assertion
Peak rate, duration/payload absent
Null dependent outputs and two missing inputs
Explicit assumptions
125 and 163, with assumed origins retained
Required rate absent
Structured error identifying requestsPerSecond
Negative rate
Invalid-field error, not a missing-field claim
Unlabeled duration
caller-unspecified; conditional daily scenario made visible
Zero values
Zeros remain supplied values rather than missing inputs
It additionally checks that account identity is unavailable in that mode. The run writes the synthetic responses to  evidence/stdio-results.json . Inspect those responses separately from any model's summary.
On November 9, 2026, this local package-based exercise passed. That is one Node test containing the scenarios above, not six independent load tests. The project's broader 0.5.0 suite contains 60 tests; those counts describe different scopes. No latency, cost-saving, adoption or hallucination-reduction percentage was measured here.

Run, verify and stop the HTTP transport

In terminal A, from  lab/ , bind the published HTTP server to loopback only:
HOST=127.0.0.1 PORT=18787 ENABLE_AWS_ACCOUNT_TOOLS=false \
node node_modules/moretes-aws-architect-mcp/dist/http.js
In terminal B, from the same directory:
curl -fsS http://127.0.0.1:18787/health
MCP_TEST_URL=http://127.0.0.1:18787/mcp npm test
Health should report version 0.5.0 and  accountTools: false . The same acceptance assertions now run through the real Streamable HTTP client. Both stdio and loopback HTTP passed on November 9; their responses are saved separately as  evidence/stdio-results.json  and  evidence/http-results.json . The runner intentionally rejects remote HTTP targets. If the port is occupied, stop your own previous lab process or choose another port consistently; never kill an unrelated process.
For cleanup, press Ctrl+C in terminal A. Confirm the health request no longer reaches that lab instance. Remove only the disposable directory you created when you no longer need the installed packages; preserve the evidence first if it is part of a review. This lab creates no AWS resources, so it has no AWS teardown step. The public AWS service is a separate deployment with its own operations runbook.
Before adapting the test, verify the resolved dependency versions in the included lockfile. For troubleshooting: if the server waits silently when run directly, it expects MCP stdio messages; use the client or CLI. If you installed another version, pin 0.5.0 before comparing outputs. If an IDE hides structured output, inspect its actual tool trace rather than interpreting the assistant's prose as the server response.

7. Keep the AWS hosting boundary narrower than the assistant

Client sends a peak-rate scenario through API Gateway to Lambda. DynamoDB quotas and CloudWatch logs

The deployed request path is client → API Gateway → Lambda. Lambda uses DynamoDB for bounded quota/aggregate-counter operations and CloudWatch for minimal operational logs. The  capacity_plan  calculation stays in memory. It does not invoke Bedrock or read customer infrastructure.
The existing deployment keeps account tools local and opt-in. The public runtime role is scoped to its own logs and quota/usage table; it is not a general architecture agent with customer credentials. Discovery annotations describe intent, while IAM and registration boundaries enforce the allowed implementation paths.
Why this split? A pure local calculation gives a fast, inexpensive feedback loop; Lambda provides a stateless shared entry point; DynamoDB makes the hosted quota survive process restarts. The trade-off is a shared public endpoint with quota and operational dependencies, not an isolated tenant or an availability SLA. Returning null protects meaning but requires client work; a permissive legacy formatter can still hide the missing data. The smaller surface is an engineering choice, not a claim that every architecture task should be public.
Public clients can inspect the  manifest  and  health . Fingerprints cover descriptors, output schemas and annotations. Compare against a reviewed baseline and exact version; a hash is neither a signature nor evidence that implementation behavior is unchanged.
For a deployment review, inspect  the stack template  and  operations runbook . The maintainer script is intentionally pinned to the owner's account. Do not run it unchanged against another account. The local exercise above creates nothing; deploying your own reviewed fork can generate AWS charges. Quotas and a budget alert are not a hard spending cap.

Acceptance checklist for your own implementation

  • Missing optional inputs remain explicit, with null dependent values.
  • Invalid required inputs are machine-readable tool errors.
  • Defaults and caller assumptions retain distinct origins.
  • Peak and sustained traffic are modeled separately.
  • Clients handle nullable results and self-reported provenance.
  • Tests exercise discovery and protocol results, not only helper arithmetic.
  • Public tools have no path to customer account credentials or provider writes.
  • External observations, calculations and model explanations remain distinguishable.
The lesson is not that a schema makes an agent trustworthy. A useful schema makes uncertainty visible enough to review. The next engineering step is to connect that visibility to evidence collection, owner approval and measured workload tests, before a scenario becomes a production decision.

References and implementation evidence

A question for reviewers: which missing input would change your next decision, and how would you require evidence for a value labeled measured? A useful counterexample is more valuable than an endorsement.
Disclosure: this explanation was prepared with AI assistance. The package-based commands and synthetic acceptance scenarios were executed; model behavior and workload performance were not benchmarked.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article