Designing MCPOrbit's tool inspector

If you spend long enough looking at MCP servers, a pattern emerges: every author has a different idea of what a tool should look like. Names, parameters, return shapes, error styles — all over the map. The job of an inspector is to make that variety legible without flattening it.

When we started on MCPOrbit's inspector, we had two anti-goals. We didn't want a generic key/value form that lost the meaning of typed parameters. And we didn't want a hand-tuned UI per server, because the whole point of the protocol is that you shouldn't need one. The brief was a single component that takes any compliant tools/list response and renders something a developer would happily use.

Starting from JSON Schema

MCP tool inputs are described in JSON Schema, which is a blessing and a curse. A blessing because it's a real type system with broad ecosystem support. A curse because real-world schemas use roughly fifteen percent of the spec, and every server uses a different fifteen percent.

Our first prototype tried to support the whole spec. It rendered every keyword, every combinator, every conditional. It was correct and unusable. We rewrote it around a core set of patterns that account for ~95% of what we saw in the wild: primitives, enums, arrays of primitives, objects with named properties, and one or two specific oneOf shapes. Everything else falls back to a JSON editor with schema-aware validation.

Mapping types to controls

Every supported type maps to one canonical control. Strings get a single-line input unless the schema says format: "textarea" or the description hints at multi-line content. Numbers get a numeric input with optional min/max sliders if both bounds are defined. Booleans get a switch. Arrays of primitives get a chip editor. Objects get a collapsible sub-form. Enums always become a select.

• `string` → text input (or textarea if length > 200 chars or format hints multi-line)
• `number` / `integer` → numeric input with stepper, slider when bounded
• `boolean` → switch with the parameter name as the label
• `array` of primitives → chip editor with type-checked entry
• `array` of objects → repeating sub-form with add/remove controls
• `object` → collapsible nested form, header shows summary of populated fields
• `enum` → select, with description text shown for the active option
• anything else → schema-aware JSON editor

Surfacing the metadata that matters

JSON Schema lets you attach a lot of metadata to a parameter — description, default, examples, deprecated, readOnly. Most inspectors ignore most of it. We took the opposite stance: every piece of metadata gets a visible affordance, but only when it's present.

Descriptions render under the field, not in a tooltip. Defaults pre-fill the control and show a small default badge so you know it wasn't typed by you. Examples appear as ghost suggestions you can click to insert. Deprecated fields render with a strikethrough header and a one-line warning. Required fields get a red dot in the label. None of this is novel in isolation — the trick is doing it consistently for every tool, on every server, without configuration.

Responses that respect their shape

MCP tools return structured responses, but most clients render them as a JSON blob. That works for one-line responses and falls apart fast for anything richer. We built a renderer that switches modes based on the declared output shape: a table view for lists of objects, a key/value view for flat objects, a timeline for arrays of timestamped entries, a markdown renderer for text/markdown content blocks.

Crucially, the raw JSON is always one click away. We never hide what came over the wire — the structured view is a presentation layer, not a replacement. Developers debugging a tool need to see the actual response, including the parts the renderer chose not to surface.

Graceful degradation, by design

Servers in the wild ship with imperfect schemas. Missing descriptions. additionalProperties: true with no other guidance. Enums where the values are integers but the labels are strings. The inspector has to do something useful with all of it.

Our rule: never refuse to render a tool. If a parameter has no type, we treat it as an open-ended JSON value and warn quietly. If the schema is malformed, we surface the parse error in a developer-readable form and fall back to a free-form JSON editor. If a returned response doesn't match the declared output schema, we render it anyway and flag the mismatch as a small warning chip — useful information for the server author, not a wall to the user.

What we'd still change

• Inline validation against `pattern` constraints — currently surfaced only on submit.
• A history view per tool so previous invocations are one click away.
• Better support for streaming responses — right now we render the final state, not the progress.
• An option to copy the input as a `tools/call` JSON-RPC request, for users debugging a server end-to-end.

Most of these are small. The inspector's foundation — strict types, visible metadata, presentational rather than authoritative response rendering, refusal to fail loudly — is the part we don't expect to revisit. It's the only set of decisions we found that worked as the variety of servers we tested it against grew, instead of fighting it.