Quickstart

Get started with @mcpjam/sdk in 5 minutes

This guide walks you through installing the SDK, connecting to an MCP server, and running your first evaluation.

Prerequisites

• Node.js 18+
• An LLM API key (Anthropic, OpenAI, etc.)

Installation

npm install @mcpjam/sdk

Step 1: Connect to an MCP Server

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

const manager = new MCPClientManager({
  everything: {
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-everything"],
  },
});

await manager.connectToServer("everything");

// List available tools
const tools = await manager.listTools("everything");
console.log("Tools:", tools.tools.map((t) => t.name));

@modelcontextprotocol/server-everything is a reference MCP server with sample tools like add, echo, and longRunningOperation.

If you’re connecting to an OAuth-protected HTTP server and already have a refresh token, pass refreshToken and clientId instead of a static access token:

const manager = new MCPClientManager({
  remoteServer: {
    url: "https://mcp.example.com/mcp",
    refreshToken: process.env.MCP_REFRESH_TOKEN!,
    clientId: process.env.MCP_CLIENT_ID!,
    clientSecret: process.env.MCP_CLIENT_SECRET,
  },
});

await manager.connectToServer("remoteServer");

The SDK will exchange the refresh token for an access token and automatically refresh it when needed.

Step 2: Execute Tools Directly

Call tools without an LLM—useful for unit tests:

const result = await manager.executeTool("everything", "add", {
  a: 5,
  b: 3,
});
console.log("5 + 3 =", result); // 8

Step 3: Create a HostRunner

Connect an LLM to your MCP tools:

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

const agent = new HostRunner({
  tools: await manager.getTools(),
  model: "anthropic/claude-sonnet-4-20250514",
  apiKey: process.env.ANTHROPIC_API_KEY,
  mcpClientManager: manager,
});

Step 4: Run Prompts

const result = await agent.run("What is 15 plus 27?");

console.log("Response:", result.getText());
console.log("Tools called:", result.toolsCalled());
console.log("Arguments:", result.getToolArguments("add"));
console.log("Latency:", result.e2eLatencyMs(), "ms");

Step 5: Write a Test

import { matchToolCalls } from "@mcpjam/sdk";
import { describe, it, expect } from "vitest";

describe("Math MCP Server", () => {
  it("should call add for addition", async () => {
    const result = await agent.run("Add 10 and 5");
    expect(matchToolCalls(["add"], result.toolsCalled())).toBe(true);
  });
});

Step 6: Run Statistical Evaluations

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

const test = new EvalTest({
  name: "addition-accuracy",
  test: async (agent) => {
    const result = await agent.run("Add 2 and 3");
    return result.hasToolCall("add");
  },
});

await test.run(agent, { iterations: 30 });

console.log(`Accuracy: ${(test.accuracy() * 100).toFixed(1)}%`);

Complete Example

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

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

  const agent = new HostRunner({
    tools: await manager.getTools(),
    model: "anthropic/claude-sonnet-4-20250514",
    apiKey: process.env.ANTHROPIC_API_KEY,
    mcpClientManager: manager,
  });

  // Quick test
  const result = await agent.run("Echo 'Hello!'");
  console.log("Response:", result.getText());
  console.log("Tools:", result.toolsCalled());

  // Run eval suite
  const suite = new EvalSuite({ name: "Basic Operations" });

  suite.add(new EvalTest({
    name: "echo",
    test: async (a) => (await a.run("Echo 'test'")).hasToolCall("echo"),
  }));

  suite.add(new EvalTest({
    name: "add",
    test: async (a) => (await a.run("Add 1 and 2")).hasToolCall("add"),
  }));

  await suite.run(agent, { iterations: 10 });

  console.log(`\nSuite accuracy: ${(suite.accuracy() * 100).toFixed(1)}%`);

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

main();

Generate evals from the Inspector

You can also generate eval code directly from the MCPJam Inspector:

1. Connect your MCP server in the Inspector
2. Click the ⋮ menu on the server card
3. Select Copy markdown for evals
4. Paste the copied markdown into an LLM (Claude, ChatGPT, etc.)
5. The LLM will generate eval test code using @mcpjam/sdk

The copied markdown is a ready-to-use prompt that includes your server’s capabilities and the full @mcpjam/sdk API reference, so the LLM has everything it needs to write your eval tests.

To save results to the MCPJam Evals dashboard, set MCPJAM_API_KEY to an MCPJam API key (sk_…) from Settings → API keys and add a mcpjam: { suiteName: "…" } block to run(). The retired project API keys (mcpjam_…) no longer work — see Saving Results.

Next Steps

Connecting to Servers

STDIO vs HTTP servers

Testing with LLMs

Prompting and result inspection

Running Evals

Statistical evaluations

API Reference

Complete API docs