Designing UX Without a Screen: Lessons from an MCP Server

A developer recounts an unusual design challenge: building an MCP (Model Context Protocol) server that exposes tools to AI clients like Claude, with no screen, buttons, or visual affordances to lean on. The entire user experience collapses into three surfaces—a tool's name and description, its input schema, and the single sentence it returns. Trust, speed, and care must all be communicated through these alone.

The piece walks through a twelve-tool MCP server running on a single Next.js route handler. It frames schema design as literally the form an AI fills out: vague field names turn every call into a guess-correct-retry negotiation. Annotations like destructiveHint and readOnlyHint are presented as the functional equivalent of a red delete button versus a plain grey one, signaling how much friction an action deserves.

On security, the most consequential design decision is that workspace identity is never passed by the caller—it's derived entirely from the authentication context (an OAuth connection or a scoped token). This means a leaked or malicious token can never reach across into another workspace; the system fails closed by design. The twelve tools are also grouped not by data schema but by user intent—look, create, edit, collaborate—treated explicitly as an information architecture decision. The broader takeaway for engineers: in screenless systems, UX decisions still exist, just encoded into strings, schemas, and returned text instead of pixels.