Build and test an MCP capacity calculator: missing inputs, explicit assumptions and AWS hosting
Given only a peak of 500 requests per second, a capacity tool cannot estimate concurrency without processing duration. Run a local MCP calculator, keep that missing value visible, then add an explicitly hypothetical duration and test the resulting scenario.
A narrow AWS hosting boundary: Capacity stays in memory; quota and logs are operational dependencies, not business evidence.
- AWS ยท public hosting
- API Gateway (edge)
- Lambda
capacity_plan(compute) - DynamoDB quota + usage (data)
- CloudWatch minimal logs (data)
Flows: client -> api: MCP / HTTP, api -> lambda: invoke, lambda -> quota: quota + counters, lambda -> logs: operational logs
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:
- A syntactically invalid request: return a tool error with the fields to fix.
- A valid but incomplete scenario: return useful partial results and explicit unknowns.
- 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:
- 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
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 s
Comments
No comments yet. Start the discussion.