HostRunner

import { HostRunner } from "@mcpjam/sdk";

new HostRunner(options: HostRunnerOptions)

const agent = new HostRunner({
  tools: await manager.getTools(),
  model: "anthropic/claude-sonnet-4-20250514",
  apiKey: process.env.ANTHROPIC_API_KEY,
  systemPrompt: "You are a helpful assistant.",
  temperature: 0.3,
  maxSteps: 5,
});

run(
  message: string,
  options?: PromptOptions
): Promise<PromptResult>

import { hasToolCall } from "@mcpjam/sdk";

// Simple prompt
const result = await agent.run("Add 2 and 3");

// Multi-turn conversation
const r1 = await agent.run("Create a task called 'Test'");
const r2 = await agent.run("Mark it complete", { context: r1 });

// Multiple context items
const r3 = await agent.run("Show summary", { context: [r1, r2] });

// Stop the loop after the step where a tool is called
const r4 = await agent.run("Search for tasks", {
  stopWhen: hasToolCall("search_tasks"),
});
console.log(r4.hasToolCall("search_tasks"));

// Bound prompt runtime
const r5 = await agent.run("Run a long workflow", {
  timeout: { totalMs: 10_000, stepMs: 2_500 },
});

if (r5.hasError()) {
  console.error(r5.getError());
}

// Exit early after selecting a tool, without waiting for the real MCP call
const r6 = await agent.run("Search for tasks", {
  stopAfterToolCall: "search_tasks",
  timeoutMs: 5_000,
});
console.log(r6.getToolArguments("search_tasks"));

// Anthropic
"anthropic/claude-sonnet-4-20250514";
"anthropic/claude-3-haiku-20240307";

// OpenAI
"openai/gpt-4o";
"openai/gpt-4o-mini";

// Google
"google/gemini-1.5-pro";
"google/gemini-1.5-flash";

// Azure
"azure/gpt-4o";

// Mistral
"mistral/mistral-large-latest";

// DeepSeek
"deepseek/deepseek-chat";

// Ollama (local)
"ollama/llama3";

// OpenRouter
"openrouter/anthropic/claude-3-opus";

// xAI
"xai/grok-beta";

const agent = new HostRunner({
  tools,
  model: "my-litellm/gpt-4",
  apiKey: process.env.LITELLM_API_KEY,
  customProviders: {
    "my-litellm": {
      name: "my-litellm",
      protocol: "openai-compatible",
      baseUrl: "http://localhost:8000",
      modelIds: ["gpt-4", "gpt-3.5-turbo", "claude-3-sonnet"],
      useChatCompletions: true,
    },
  },
});

const tools = await manager.getTools();
const agent = new HostRunner({ tools, ... });

model: "anthropic/claude-sonnet-4-20250514";

apiKey: process.env.ANTHROPIC_API_KEY;

systemPrompt: "You are a task management assistant. Be concise.";

temperature: 0.1; // More deterministic, better for testing
temperature: 0.9; // More creative

const agent = new HostRunner({
  tools: await manager.getTools(),
  model: "openai/gpt-5",
  apiKey: process.env.OPENAI_API_KEY,
  reasoningEffort: "high",
});
agent.getReasoningEffort(); // "high"

maxSteps: 5; // Stop after 5 tool calls

// Testing an OpenAI Apps SDK widget (ChatGPT / Copilot host)
const agent = new HostRunner({
  tools,
  model: "openai/gpt-4o",
  apiKey: process.env.OPENAI_API_KEY,
  mcpClientManager: manager,
  injectOpenAiCompat: true,
});

// Testing a SEP-1865 widget (Claude / Cursor / Codex host) — default
const agent = new HostRunner({
  tools,
  model: "anthropic/claude-sonnet-4-20250514",
  apiKey: process.env.ANTHROPIC_API_KEY,
  mcpClientManager: manager,
  // injectOpenAiCompat defaults to false
});

import { hasToolCall } from "@mcpjam/sdk";

// Stop after the step where "search_tasks" is called
const result = await agent.run("Find my open tasks", {
  stopWhen: hasToolCall("search_tasks"),
});

expect(result.hasToolCall("search_tasks")).toBe(true);

// Stop after any of multiple conditions
const result2 = await agent.run("Do something", {
  stopWhen: [hasToolCall("tool_a"), hasToolCall("tool_b")],
});

const result = await agent.run("Run a long workflow", {
  timeout: 10_000,
});

const result2 = await agent.run("Run a long workflow", {
  timeout: { totalMs: 10_000, stepMs: 2_500, chunkMs: 1_000 },
});

import { MCPClientManager, HostRunner } from "@mcpjam/sdk";

async function main() {
  // Setup
  const manager = new MCPClientManager({
    everything: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-everything"],
    },
  });
  await manager.connectToServer("everything");

  // Create agent (pass manager when you need widget snapshots or MCPJam replay configs)
  const agent = new HostRunner({
    tools: await manager.getTools(),
    model: "anthropic/claude-sonnet-4-20250514",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "You are a helpful assistant.",
    temperature: 0.3,
    maxSteps: 10,
    mcpClientManager: manager,
  });

  // Single prompt
  const r1 = await agent.run("What is 15 + 27?");
  console.log(r1.text);
  console.log("Tools:", r1.toolsCalled());

  // Multi-turn
  const r2 = await agent.run("Now multiply that by 2", { context: r1 });
  console.log(r2.text);

  // Error handling
  if (r2.hasError()) {
    console.error("Error:", r2.getError());
  }

  // Cleanup
  await manager.disconnectServer("everything");
}