DEV Community

Fernando Azevedo
Fernando Azevedo

Posted on Originally published at fernando.moretes.com

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:

  1. A syntactically invalid request: return a tool error with the fields to fix.
  2. A valid but incomplete scenario: return useful partial results and explicit unknowns.
  3. 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 [email protected] \
  moretes-architect call capacity_plan \
  --arg requestsPerSecond=500 --arg rateType=peak \
  --arg 'inputProvenance={"requestsPerSecond":"provided"}'
Enter fullscreen mode Exit fullscreen mode

The important fields are:

{
  "validated": false,
  "status": "insufficient-inputs",
  "insufficientInputs": ["durationMs", "payloadKB"],
  "averageConcurrency": null,
  "plannedConcurrency": null,
  "dailyRequests": null,
  "dailyPayloadGB": null
}
Enter fullscreen mode Exit fullscreen mode

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')
};
Enter fullscreen mode Exit fullscreen mode

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' });
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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 [email protected] \
  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"}'
Enter fullscreen mode Exit fullscreen mode

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" }
}
Enter fullscreen mode Exit fullscreen mode

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" }]
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

A client calls capacity_plan through API Gateway and Lambda. DynamoDB quotas and CloudWatch logs are operational dependencies; missing duration and payload remain unknown in the structured result.

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.

Production review through six lenses

  • operational-excellence: Pin versions, inspect actual tool traces, retain synthetic acceptance responses and review descriptor changes before upgrades.
  • security: Keep account/provider tools out of public registration and scope runtime IAM to its own operational stores. Never send customer inputs to this public exercise.
  • reliability: Separate invalid requests from valid incomplete scenarios. Unknown inputs stay explicit; a successful calculation is not an availability guarantee.
  • performance: Bound input sizes and calculate locally; obtain workload distributions and tail-latency evidence before sizing downstream systems.
  • cost: The local lab creates no AWS resources. Hosted requests consume service capacity; quota and budget alerts are not hard spending caps.
  • sustainability: Reuse deterministic local calculations and stop the disposable HTTP process after verification. No environmental savings metric is claimed.

Anti-patterns

  • Replacing unknowns with zero or invented defaults.
  • Treating a peak rate as sustained daily traffic.
  • Treating a measured label, passing test or descriptor hash as independently verified business evidence.

C4

A client requests scenario arithmetic from the public workbench; authenticated customer-account operations remain local and opt-in.

Containers

  • MCP client (MCP SDK / stdio or HTTP): Supplies scenario inputs and renders structured results.
  • Public AWS runtime (API Gateway / Lambda / DynamoDB / CloudWatch): API Gateway and Lambda serve stateless MCP requests with scoped operational storage.

Components

  • Input contract: Strict schema, optional unknowns and structured invalid-input paths.
  • Deterministic calculator: Computes dependent values only when inputs are available.
  • Evidence projection: Retains self-reported origins and visible limitations.

Verdict

Use typed, partial results to make uncertainty reviewable. Require separate workload evidence before accepting a capacity decision.


Originally published at fernando.moretes.com. By Fernando F. Azevedo: Senior Solutions Architect.

Top comments (0)