MCPJam Inspector

MCPJam provides four distinct surfaces for developing and testing MCP servers, MCP apps, and ChatGPT apps:

1. Inspector: An IDE-style workspace for MCP development. Features include chatting with frontier models, manual tool invocation, widget rendering, and side-by-side comparison of hosts and models.
2. CLI: A stateless tool designed for connectivity checks, OAuth, conformance testing, and tool execution. Includes JUnit/JSON reporters for CI integration.
3. SDK (@mcpjam/sdk): A TypeScript toolkit for writing unit tests, end-to-end (e2e) tests, and evaluations. It is compatible with Jest and Vitest.
4. Hosted: A browser-based version at app.mcpjam.com that allows you to share servers and sessions with your team.

The Sip Cocktails MCP App is a demonstration application that serves cocktail recipes through a Model Context Protocol (MCP) interface. It features an interactive React UI widget and uses Convex for data storage and image management.

Key Capabilities:

• Interactive UI: A React-based cocktail recipe widget displaying images, instructions, nutrition, and ingredient measurements.
• MCP Tools: Provides tools to fetch specific cocktail details and list all available cocktail IDs and names.
• Data Backend: Uses Convex queries and mutations for managing cocktails, ingredients, and image storage.
• Data Seeding: Includes scripts for populating the database and uploading images.

An MCP Client is a named, reusable configuration that defines how MCPJam connects to and communicates with your MCP servers. It acts as a host emulator, allowing you to bundle model settings, system prompts, attached servers, protocol-level configurations, and MCP App sandbox controls into a single selectable profile.

Key Benefits

• Reproducibility: Capture a snapshot of all settings (model, prompt, servers) so runs can be shared and repeated with identical conditions.
• Host Emulation: Configure the inspector to mimic specific environments like Claude Desktop, ChatGPT, or Cursor to verify how your server or MCP App behaves under their specific sandbox policies and capabilities.
• Faster Iteration: Switch between complex configurations (e.g., different protocol versions or CSP modes) with a single click.

MCP Apps can use a standardized set of CSS variables provided by the host to ensure consistent theming. To ensure graceful degradation when a host does not provide all variables, apps should always define fallback values in their :root or local scope.

Best Practices:

• Use the light-dark() CSS function for theme-aware values.
• Use utilities like applyHostStyleVariables or the useHostStyleVariables React hook to populate variables.
• Use applyDocumentTheme or useDocumentTheme to respond to Host Context theme changes.

Example CSS usage:

.container {
  background: var(--color-background-primary);
  color: var(--color-text-primary);
  font-family: var(--font-sans);
}

:root {
  --color-text-primary: light-dark(#171717, #000000);
  --border-radius-small: 8px;
}

The PromptResult class wraps every response returned by HostRunner.run(). It is the primary object used to inspect the outcome of an agent execution, including text responses, tool calls, errors, performance metrics, and conversation history.

Note: You do not import PromptResult directly; it is returned by the agent.run() method.

// PromptResult is returned by HostRunner.run()
// You don't import it directly

const result = await agent.run("...");
// result is a PromptResult

Every market host in @mcpjam/sdk includes an imageSupport field within its HostCompatProfile. This describes how the host handles MCP tool-result images across three specific sources:

1. toolImageContent: Direct MCP image blocks.
2. embeddedResourceImages: Image blobs inside MCP resources.
3. resourceLinkImages: Image links resolved via resources/read.

Each source tracks:

• model: Whether the image is passed to the LLM.
• ui: Whether the host UI renders the image.
• placement: Where the preview appears ("inline" | "collapsed" | "none").

New exported types from @mcpjam/sdk/host-compat:

• HostImageSupport
• ImageSourceSupport
• ImagePlacement