Clients

Reusable MCP client configurations for testing servers and apps under realistic conditions

A Client is a named, reusable configuration that defines how MCPJam connects to and talks to your MCP servers when you test them in Chat, Chatboxes, and Evals. It bundles everything that would normally be scattered across one-off settings — model, system prompt, attached servers, protocol-level knobs, and MCP App sandbox controls — behind a single picker.

Real MCP hosts (Claude Desktop, ChatGPT, Cursor, your own product) each advertise slightly different capabilities and apply different sandbox policies to MCP Apps. Clients let you reproduce those environments in MCPJam so you can verify your server behaves correctly before shipping to a specific host.

Why Clients exist

Without Clients, every Chat or Eval would be tied to whatever ambient settings were active when you ran it. That makes results hard to reproduce and hard to share. Clients fix this by giving you:

• Reproducibility — A snapshot of every setting that affects a run, so a teammate hitting the same Client gets the same conditions.
• Host emulation — Configure the inspector to look like Claude Desktop, ChatGPT, or your own host so you can verify your MCP server or MCP App degrades gracefully across them.
• Faster iteration — Switch between configurations with one click instead of editing fields in five places.

What you can configure

A Client groups settings into two layers: the protocol layer (how the MCP connection itself behaves) and the app layer (what an MCP App running inside the client is allowed to do).

Protocol-level settings

These map directly to fields the inspector sends during the standard MCP initialize handshake and on every subsequent request.

• Supported protocol versions — The ordered list of MCP protocol versions the client advertises. The first entry is sent as protocolVersion; the rest form the accept-set. Useful for testing how your server handles older or newer clients.
• clientInfo — The name, version, and any additional fields sent in initialize.params.clientInfo. Set this to match a real host’s identifier when you want your server to take a host-specific code path.
• Client capabilities — The capabilities object sent in initialize (sampling, roots, elicitation, experimental, etc.). Enable or disable each one to test what your server does when a capability is missing.
• Request timeout — Per-request timeout in milliseconds applied to all MCP calls (tools/call, resources/read, etc.). Lower it to verify your server handles cancellation correctly; raise it for long-running tools.
• Default headers — Headers attached to every HTTP-transport request. Useful for auth tokens, tenant IDs, or anything else your server expects upstream.

Per-server connection overrides

You can override the request timeout and headers per server attached to the Client. This lets a single Client talk to one server with a long timeout and an auth header while keeping defaults for the others.

MCP App settings (SEP-1865)

When your server exposes MCP Apps — interactive UIs delivered via ui:// resources — the Client controls how the inspector renders and sandboxes them. These map to the fields a real host advertises in HostCapabilities and HostContext.

• Host capabilities — Toggle which app-facing features the inspector advertises: openLinks, serverTools, serverResources, logging. Use this to simulate hosts that don’t support all of them and confirm your app degrades gracefully.
• Sandbox CSP mode — host-default, declared, or relaxed. Controls the baseline Content Security Policy the inspector applies to your app’s iframe.
• CSP restrictTo — Per-directive intersections (connectDomains, resourceDomains, frameDomains, baseUriDomains) that further narrow what the app is allowed to fetch, embed, or set as a base URI. Restrict-only — the inspector never adds an undeclared domain.
• Custom CSP directives — Verbatim source-expression overrides (e.g. script-src: 'unsafe-eval' 'wasm-unsafe-eval') for cases where you need to model exactly what a particular host emits at the browser layer.
• Permission Policy — Per-feature toggles for camera, microphone, geolocation, and clipboard-write. Choose resource-declared (grant what the app’s resource metadata asks for), deny-all, or custom (your own allow map).
• Display modes — Which of inline, fullscreen, and pip the inspector advertises in HostContext.availableDisplayModes. Test how your app responds when a requested mode isn’t available.
• Theme and styles — The CSS variables and font block the inspector injects into HostContext.styles so you can verify your app picks up host theming.

All MCP App settings only take effect when the connected server actually delivers a ui:// resource. For plain tool-only servers, the protocol-level settings are what matter.

Creating a Client

1. Open the Clients tab in the inspector.
2. Click New Client.
3. Give it a name (e.g. Claude Desktop, ChatGPT, Strict CSP).
4. Pick the servers it should attach to.
5. Open the focus panel to drill into protocol or MCP App settings.
6. Click Save.

The canvas on the left shows a live diagram of the Client — the model, attached servers, and any per-server overrides. Cards flash briefly when you switch between Clients so you can see what changed.

Using a Client

Once saved, a Client shows up in the picker at the top of every consumer:

• Chat — Drives the model, system prompt, attached servers, and connection settings for the conversation.
• Chatboxes — Same as Chat, but persisted as a saved chatbox configuration.
• Evals — Every test run inside an Eval uses the selected Client, so results are reproducible across teammates.

Switching the active Client in any of these views swaps the entire configuration in place. There’s no separate “apply” step.

Managing Clients

From the Clients index page:

• Duplicate — Copy a Client when you want a small variant (e.g. Claude Desktop — strict CSP) without rebuilding from scratch.
• Delete — Removes the Client. The inspector blocks deletion if any chatbox or eval still depends on it; resolve those first, or use force delete if you’re sure.

Keep one Client per host you intend to ship to. Duplicate it to make scoped variants for individual debugging sessions instead of editing the original — that way your “known-good” baselines stay stable.

Sharing across a project

Clients are scoped to the project, like servers and views. Every member of a shared project sees the same Client list and any saves sync automatically. This means a teammate can reproduce your exact test conditions by selecting the same Client from the picker — no copy-pasting settings.

Best practices

• Mirror your target hosts. Create one Client per real host you care about (Claude Desktop, ChatGPT, your own product) and keep its clientInfo, capabilities, and sandbox settings aligned with what that host actually advertises.
• Test the negative paths. Build a “minimal” Client with most capabilities disabled and a strict CSP — running your server against it surfaces assumptions that won’t hold on more restrictive hosts.
• Pin Evals to a Client. Always select a Client before running an eval suite so the results are reproducible. Evals run against ambient settings drift the moment someone toggles something elsewhere.
• Duplicate before debugging. When you’re chasing a bug, duplicate the Client first and tweak the copy. Your baseline stays intact for comparison.