DEV Community: takeaseat

Testing an MCP server at the stdio boundary: handshake, discovery, and real calls

takeaseat — Mon, 03 Aug 2026 14:37:31 +0000

Unit tests can tell you that a function returns the right object. They cannot, by themselves, tell you that a spawned MCP server completes its initialization handshake, advertises the tools a client expects, keeps protocol frames on stdout, or turns a real tool call into a valid response.

That process boundary is where a useful class of integration bugs hides.

This article shows a small, sequential stdio smoke test for a Node.js MCP server. The example is a cron-expression server, but the test shape applies to any MCP server launched as a child process.

The boundary to test

An MCP server using stdio has two streams with different jobs:

stdout carries protocol messages.
stderr carries diagnostics intended for humans.

A debug console.log() in the wrong place can corrupt stdout and make a correct handler look like a broken server. The server in this example starts with the MCP SDK's StdioServerTransport and logs its startup message with console.error, not console.log:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // stdout is reserved for MCP protocol frames.
  console.error(`[${SERVER_NAME}] v${SERVER_VERSION} running on stdio`);
}

The other part of the boundary is the request sequence. A client must initialize the connection before asking for tools or calling one:

send initialize;
send the notifications/initialized notification;
request tools/list;
call a tool through tools/call.

A unit test that invokes a handler directly skips all four steps.

A minimal smoke-test harness

Save this as e2e-smoke.js in the repository root. It deliberately spawns the real entry point instead of importing the handler functions.

'use strict';

const { spawn } = require('node:child_process');

const child = spawn(process.execPath, ['index.js'], {
  stdio: ['pipe', 'pipe', 'pipe'],
});

let buffer = '';
let nextId = 1;
const pending = new Map();

child.stdout.on('data', (chunk) => {
  buffer += chunk.toString();

  let newline;
  while ((newline = buffer.indexOf('\n')) !== -1) {
    const line = buffer.slice(0, newline).trim();
    buffer = buffer.slice(newline + 1);
    if (!line) continue;

    let message;
    try {
      message = JSON.parse(line);
    } catch (error) {
      for (const { reject } of pending.values()) reject(error);
      pending.clear();
      continue;
    }

    if (message.id !== undefined && pending.has(message.id)) {
      pending.get(message.id).resolve(message);
      pending.delete(message.id);
    }
  }
});

child.stderr.on('data', (chunk) => {
  process.stderr.write(`[server] ${chunk}`);
});

function request(method, params) {
  const id = nextId++;
  const message = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';

  return new Promise((resolve, reject) => {
    pending.set(id, { resolve, reject });
    child.stdin.write(message);
  });
}

function notification(method, params) {
  child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
}

function assert(condition, message) {
  if (!condition) throw new Error(message);
}

async function main() {
  try {
    const initialized = await request('initialize', {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'smoke-test', version: '1.0.0' },
    });
    assert(!initialized.error, 'initialize failed');
    assert(initialized.result?.serverInfo?.name === 'cron-mcp-server', 'wrong server name');

    notification('notifications/initialized', {});

    const listed = await request('tools/list', {});
    const names = listed.result?.tools?.map((tool) => tool.name) ?? [];
    assert(!listed.error, 'tools/list failed');
    assert(names.length === 4, `expected 4 tools, got ${names.length}`);

    const parsed = await request('tools/call', {
      name: 'parse_cron',
      arguments: { expression: '*/5 * * * *' },
    });
    assert(!parsed.error, 'parse_cron failed');

    const validated = await request('tools/call', {
      name: 'validate_cron',
      arguments: { expression: '0 0 30 2 *' },
    });
    const validationText = validated.result?.content?.[0]?.text ?? '';
    assert(!validated.error, 'validate_cron failed');
    assert(validationText.includes('never'), 'semantic warning was not returned');

    const nextRuns = await request('tools/call', {
      name: 'next_runs',
      arguments: { expression: '0 9 * * 1-5', count: 3 },
    });
    assert(!nextRuns.error, 'next_runs failed');

    console.log('stdio MCP smoke test: PASS');
  } finally {
    child.kill();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

There are a few details worth keeping:

The harness reads stdout line by line and parses every response as JSON.
Requests are sent sequentially. That keeps the example small and makes each failure attributable to one step.
The server's stderr is forwarded separately, so diagnostics do not get mistaken for protocol frames.
The test checks a semantic result, not just an HTTP-like success. 0 0 30 2 * has five syntactically valid fields, but February 30 does not occur. The expected result is therefore a valid parse plus a warning/observation that the schedule never fires.

Run the unit and process tests separately

From the repository root:

npm ci
npm test
node e2e-smoke.js

The project also includes a checked-in end-to-end script that exercises the same boundary with initialize, tools/list, parse_cron, validate_cron, next_runs, and cron_presets.

In the source checkpoint used for this article, the unit suite completed with 19 passing tests and no failures. The real stdio script completed its handshake, found four tools, returned responses for all four calls, and reported PASS.

Those are two different signals:

Unit tests cover transformations and edge cases in the cron engine and the expected MCP-shaped output.
The stdio test covers process startup, transport framing, initialization order, tool registration, and the actual child-process boundary.

Keeping both is useful because either one can pass while the other fails.

What this catches that direct tests miss

Accidental stdout logging

If the server prints a banner with console.log, the first line on stdout is no longer a protocol frame. The JSON parser in the harness will fail immediately. Keep logs on stderr and make that a code-review rule.

A server that starts but advertises the wrong tools

A process can stay alive while registering no tools, using a renamed tool, or exposing a schema the client does not expect. The tools/list assertion catches a missing or renamed registration before a user tries to call it.

Confusing syntax validity with schedule usefulness

The validate_cron call is intentionally made against an impossible calendar date. The server returns valid: true for the expression's syntax, while its observations explain that the schedule is impossible. That distinction is more useful to a caller than collapsing every problem into a single boolean.

Broken request sequencing

Calling tools/list before initialization is a client bug. A direct function test cannot detect it. The harness models the real order and sends the initialized notification before discovery.

Output that is not actually serializable

The server returns text content containing JSON for its tools. Parsing the outer JSON-RPC response and then inspecting the content forces the test to exercise the wire format, not just an in-memory JavaScript object.

Keep the harness honest

A smoke test is not a protocol certification suite. This one does not prove:

every cron grammar extension;
concurrent request behavior;
client-specific UX;
long-running process stability;
production deployment health; or
that a schedule is operationally appropriate for a particular workload.

It also does not replace unit tests. The source tests deliberately exercise invalid expressions, named days, next-run calculations, custom dates, presets, and JSON serialization. The process test adds the missing transport seam.

If the server later gains more tools, update the expected tool list and add one meaningful call for each new behavior. If the server gains notifications or progress messages, make the harness distinguish responses from notifications rather than assuming every line has an id.

Practical takeaway

For a stdio MCP server, “the handler works” and “the server works” are different claims. Test the smallest real client flow you depend on:

spawn the actual entry point;
keep stdout protocol-only;
complete initialization;
discover the registered tools;
make representative calls;
assert on both wire shape and semantic content; and
terminate the child cleanly.

This is a small amount of code, but it verifies the boundary where a server stops being a collection of functions and becomes a process another tool can actually use.

The complete server used in this example is available in the cron-mcp-server npm package.

Disclosure: This article was created with the help of AI. The examples and factual claims were checked against the source checkout and the published package metadata; the test results reported above came from an actual local run.

The SSRF check that passed every test and still had a fail-open branch

takeaseat — Sun, 02 Aug 2026 08:10:12 +0000

When an SSRF check cannot resolve a hostname, “allow and let the browser fail” is not a safe fallback.

A URL-rendering service usually performs two separate actions:

resolve the hostname to decide whether the destination is private; and
let a browser fetch the page, including redirects and subresources.

If DNS resolution fails and the guard returns “not blocked”, the decision is fail-open. A later retry, a resolver change, or a rebinding window can produce an address the original check never approved. The browser request may also be a different URL from the one checked, so the guard has to run at the request boundary too.

The safe default is small and boring:

const dns = require('node:dns');

async function isBlockedSSRF(targetUrl) {
  const parsed = new URL(targetUrl);
  if (!['http:', 'https:'].includes(parsed.protocol)) return 'blocked_scheme';

  const host = parsed.hostname.toLowerCase();
  if (isPrivateIp(host)) return 'private_ip';

  try {
    const addresses = await dns.promises.lookup(host, { all: true });
    for (const address of addresses) {
      if (isPrivateIp(address.address)) return 'resolved_private';
    }
  } catch {
    // Unknown is not public. Fail closed.
    return `dns_resolution_failed:${host}`;
  }

  return null;
}

That function is necessary but not sufficient. In a Playwright renderer, route every browser request (**/*), not only the initial page. Apply the same check to images, stylesheets, iframes, fetches, and redirect targets. Block link-local and metadata addresses, IPv4-mapped IPv6 forms, unspecified/local IPv6, and carrier-grade NAT ranges. Keep the URL length and scheme allowlists before DNS work.

The regression test should force the resolver to throw, then assert a block reason—not merely assert that the function does not crash. In the implementation I worked on, the production helper was separated from a copied test fixture, the forced-DNS-failure case was added, and the security suite ended at 21 passed and 0 failed. The deployed container was then checked as a non-root node process; its direct origin, independent VM-WAN path, and public edge health all returned HTTP 200 after the change.

There is a trade-off: fail-closed DNS behavior can reject legitimate renders during resolver incidents. That is an availability cost, but it is the correct side of the security boundary for a service that fetches attacker-selected URLs. Operators can add retry/backoff or an explicit, audited allowlist later; silently treating an unknown destination as public is not a recovery strategy.

If you are building a URL-to-document service, the practical checklist is:

reject non-HTTP(S) schemes before DNS;
reject private and special-use IPs in every address family;
fail closed on resolver errors and empty answers;
re-check every browser request and redirect;
test the real helper used in production;
verify the image contains the helper after deployment.

For a live example of the managed PDF API discussed here, see https://pdffleet.com/docs

Your cron expression can be valid and still never run

takeaseat — Sun, 02 Aug 2026 06:44:56 +0000

Your cron expression can be valid and still never run

A cron parser can answer one question—does this have five fields and legal tokens?—while your scheduler needs a different answer: will this job ever run, and will it run when I intended?

That gap is where silent cron failures live. A schedule can be syntactically valid, return no parser error, and still be impossible, surprisingly broad, or operationally noisy. Here is a small semantic checklist you can run before deploying a schedule.

1. Check the calendar, not only the grammar

Consider:

0 0 30 2 *

This has the right five-field shape: minute, hour, day of month, month, day of week. But February has no day 30. A syntax-only validator can label it valid, while a calendar-aware validator should tell you that its approximate frequency is never.

That distinction is important in CI: treat a parse error as a broken input, but treat an impossible calendar match as a review failure. Both deserve attention, but they need different messages.

The same idea applies to leap days. 0 0 29 2 * is meaningful, but it does not fire in non-leap years. Whether that is correct depends on the job; the validator should surface the edge case instead of silently deciding for you.

2. Be explicit about day-of-month/day-of-week semantics

This expression is a classic source of surprises:

0 0 1,15 * 1

Many traditional cron implementations treat a restricted day-of-month and a restricted day-of-week as an OR, not an AND. In that model, the job runs on the 1st, the 15th, or Monday. Someone reading the expression as “the 1st or 15th when it is Monday” will get a different schedule.

This is not a universal rule across every scheduler, so check the documentation for the runtime that will execute the job. The useful validation behavior is to warn whenever both fields are restricted and force the author to choose the intended semantics.

For example, a lightweight pre-deployment check can start like this:

function semanticWarnings(expression) {
  const fields = expression.trim().split(/\s+/);
  if (fields.length !== 5) {
    return [{ level: 'error', message: 'Expected five cron fields' }];
  }

  const [minute, hour, dayOfMonth, , dayOfWeek] = fields;
  const warnings = [];

  if (dayOfMonth !== '*' && dayOfWeek !== '*') {
    warnings.push({
      level: 'high',
      message: 'Confirm whether day-of-month and day-of-week are OR or AND',
    });
  }

  if (minute === '0' && hour === '0') {
    warnings.push({
      level: 'info',
      message: 'This runs at midnight; check for a synchronized load spike',
    });
  }

  return warnings;
}

This is deliberately not a complete cron parser. It is a policy layer that catches questions a grammar check cannot answer. Keep it alongside a real parser rather than replacing one with string comparisons.

3. Explain stepped schedules as a sequence

*/7 * * * * is valid, but it is not the same thing as “every seven minutes” in the wall-clock sense. Its minute values are:

0, 7, 14, 21, 28, 35, 42, 49, 56

The next hour starts at minute 0 again. The final gap in the hour is four minutes, not seven. A live validation response for this expression reports exactly that uneven boundary.

This matters for polling, rate limits, and systems where evenly distributed work is the goal. If you need a true elapsed-time interval, a cron expression may be the wrong primitive; use a scheduler that supports interval-based execution or persist the next due time.

4. Treat midnight as an operational decision

0 0 * * * is easy to read, but it also puts every matching job at the same minute. A semantic validator can suggest a small offset—such as 2 0 * * *—when the workload does not require the exact boundary. That is not a correctness fix; it is a way to reduce avoidable synchronization.

Do not blindly rewrite schedules. Emit the suggestion, then let the owner decide whether the timing is contractual.

A practical validation pipeline

A practical review can use four stages when checking a schedule:

Shape: split on whitespace and require five fields (or the exact format your runtime supports).
Token validity: validate ranges, lists, steps, names, and special forms with a real cron parser.
Calendar reachability: check restricted dates against the selected months and leap-year behavior.
Operational intent: flag OR/AND ambiguity, uneven steps, synchronized boundaries, and unexpectedly high frequency.

The response should preserve these as separate findings. Returning only valid: true throws away the most useful part of the analysis. A better result has a boolean for parse validity plus structured warnings, observations, and suggestions, so CI can fail on high-severity findings while a human can review informational ones.

Test the same contract in CI and production

Keep the endpoint or library under test configurable so the same checks run against a local build and the deployed service:

export API_BASE='https://your-api.example'

response=$(curl -fsS --get "$API_BASE/api/cron/validate" \
  --data-urlencode 'expr=0 0 30 2 *')

node -e '
  const result = JSON.parse(process.argv[1]);
  if (result.valid !== true) process.exit(1);
  const text = JSON.stringify(result);
  if (!text.includes("never (impossible schedule)")) process.exit(2);
' "$response"

The assertion above is intentionally narrow: it checks that the expression parses but is still identified as impossible. Add equivalent cases for your scheduler’s day-field semantics and any extensions it supports.

The key lesson is simple: syntactic validity is a starting point, not a deployment approval. A useful cron validator explains what the schedule means, whether it can reach a real date, and which operational assumptions deserve review.

If you want to try these checks against the hosted implementation, use the Cron Validator API.