Build a small MCP server with validated tools

The prerequisite Easy question looked at MCP from the assistant's side. This question builds the other end, a server.

Tools are model-controlled: the model discovers them and proposes calls, and a human should always be able to deny an invocation. Servers can also offer resources and prompts; this question builds tools only.

The validated adapter prerequisite checks calls to a tool your own application runs. An MCP server keeps that habit behind a public protocol: any MCP host can call it, so it checks every call against the schema it published.

MCP messages travel over a transport. With stdio, the client starts the server as a local process and exchanges messages over its standard input and output; the server takes credentials from the environment. With Streamable HTTP, the server is an HTTP service.

The 2026-07-28 revision (current as of November 2026) is stateless: there is no initialize handshake, and every request carries its protocol fields in params._meta.

A request missing a required field is malformed and must be rejected with -32602. Servers must not rely on earlier requests for the version, capabilities, or client identity; state that spans requests is referenced by an explicit identifier the client passes each time. Servers must also implement server/discover, which returns the versions and capabilities they support.

So a request handler can be a pure function of one message plus the server's configuration, which is what you build here.

Every MCP message is a JSON-RPC 2.0 object with "jsonrpc": "2.0". A request has an id (in MCP a string or an integer, never null) and is answered exactly once by a response with the same id, holding either result or an error object { "code", "message", "data"? }. A notification is a well-formed request object with no id member, and it is never answered, not even with an error; a malformed message is not a notification. When a malformed message's id cannot be read, JSON-RPC answers with "id": null, and a parse error (-32700) happens before a handler sees parsed JSON. Every MCP result carries resultType: "complete" means final, and "input_required", which asks the client for more input, is out of scope here.

handleMcpRequest(message, server) (Python handle_mcp_request) receives one already-parsed JSON value and returns one response object, or null (Python None) when nothing may be sent. Apply the checks in order; the first failure decides the response.

Validation reads only additionalProperties: false, required, and, per property, type (string or integer), enum, minimum, and maximum; other keywords, such as default, are ignored. Report only the first failure, in this order:

1. With additionalProperties: false, each argument key, in the order the arguments list them, that properties does not declare: Unexpected argument: <key>. Without it, extra keys are allowed (the JSON Schema default).
2. Each name in required, in order, that is missing: Missing required argument: <name>.
3. Each declared property, in properties order, that is present: type (Argument <name> must be a string or Argument <name> must be an integer), then enum (Argument <name> must be one of: <values joined by ", ">), then minimum (Argument <name> must be at least <minimum>), then maximum (Argument <name> must be at most <maximum>).

An integer, for arguments and ids alike, is a number with no fractional part, as in JSON Schema 2020-12: booleans and numeric strings are not integers.

Tool results:

• A tool result is { resultType: "complete", content: [{ type: "text", text }], structuredContent, isError }. Failures carry no structuredContent.
• get_build_status: find the build with the same pipeline and build. None: No build <build> found for pipeline <pipeline>. Found: structuredContent is a new object { pipeline, build, status, minutes }.
• list_flaky_tests: the pipeline's flaky tests in stored order, at most limit (3 when absent). structuredContent is { pipeline, tests: [{ test, failures }, ...] }.
• On success, text is the compact JSON of structuredContent, with no spaces and keys in the order shown.

The server/discover and tools/list result shapes, the response envelope, and the language-specific details are listed with the implementation exercise and in the practice problem.

Two forms of a result. content holds blocks for the model and for older clients; structuredContent holds a JSON value for programs. A tool that returns structured content should also return it as serialized JSON in a text block, which is why this server's success text mirrors structuredContent.

What isError means. isError: true says the call did not produce what the tool promises: the input failed validation, the requested record does not exist, or an upstream system failed. Clients pass these results to the model so it can fix its arguments and retry.

Caching fields. ttlMs hints how long, in milliseconds, a client may treat the list as fresh. A cacheScope of public (no caller-specific data) lets any client or shared cache reuse the list across authorization contexts; private limits reuse to one authorization context, which a server needs when its tools depend on the caller's grants.

Order and names. Return tools in a deterministic order so clients and prompt caches can reuse the list. Names should be unique within a server and treated as case-sensitive; a host that aggregates servers should disambiguate collisions. The model reads names, descriptions, and schemas when it decides what to call, so write them as carefully as a prompt.

Read the request contract before you start. Each row is one message sent to ci-insights.

Write handleMcpRequest(message, server) in JavaScript (the reference below is TypeScript), or handle_mcp_request(message, server) in Python. The function receives already-parsed JSON, so reading bytes from stdin is out of scope. The practice problem passes the server in as the second argument so its tests can vary the configuration, the tool order, or a schema.

Adding an MCP server changes what an assistant can do and what its model reads. Review it like a dependency that runs with your credentials.

1. A local server is code you run. A stdio server runs with the same privileges as the client that started it, and installing one means running code someone else published.
2. Definitions are model input. A malicious server can hide instructions in names, descriptions, or schemas that the user never sees (tool poisoning), change its definitions after approval (a rug pull), or steer the model toward misusing another server's tools (shadowing).
3. Annotations are claims. Hints such as readOnlyHint are what the server says about its own tools. Clients must treat them as untrusted unless the server is trusted, and no hint limits what the code can do.
4. Output is data. A trustworthy server can still return text other people wrote, such as issue bodies or log lines, and that text can carry instructions. Security & Privacy (security-privacy-easy-prompt-injection, a prerequisite of the Easy question) covers prompt injection; it applies here unchanged.

Servers have duties too: validate all tool inputs, enforce access control, rate limit tool calls, sanitize tool outputs, and never fetch a network $ref automatically while validating.

Apply the trust model to three proposals for ci-insights. For each one, work out what runs and what the model reads before you decide.

Revisions in use. The 2026-07-28 specification calls revisions with per-request _meta modern, and those that open with an initialize handshake (2025-11-25 and earlier) legacy. A dual-era server serves both, handling a client that opens with initialize under the legacy revision. ci-insights is modern-only: work out from the request contract what a 2025-11-25 client receives and what the team could change. A client also treats a missing resultType from an older server as "complete".

Where argument errors go. The 2025-11-25 revision clarified that input validation errors are tool execution errors, not protocol errors, so the model can correct itself, and the 2026-07-28 tools page keeps that rule. The 2026-07-28 schema reference still shows an "invalid tool arguments" example under -32602, which conflicts with the tools page; this exercise follows the tools page. Some servers still use -32602 for argument problems, so clients should handle both channels.