> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-2977-1782862320032.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
npm install @mcpjam/sdk
```

## Step 1: Connect to an MCP Server

```typescript theme={null}
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));
```

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

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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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`

<Frame>
  <img className="block" src="https://mintcdn.com/mcpjam-mintlify-docs-update-pr-2977-1782862320032/QjqOmQ0NMf30Ekw8/images/copy-markdown-menu.png?fit=max&auto=format&n=QjqOmQ0NMf30Ekw8&q=85&s=cf774c06caf5b7d59e07ad5061fb2fdc" alt="Copy markdown for evals menu option" width="300" data-path="images/copy-markdown-menu.png" />
</Frame>

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.

<Tip>
  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](/sdk/concepts/saving-results).
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Connecting to Servers" icon="plug" href="/sdk/concepts/connecting-servers">
    STDIO vs HTTP servers
  </Card>

  <Card title="Testing with LLMs" icon="bot" href="/sdk/concepts/testing-with-llms">
    Prompting and result inspection
  </Card>

  <Card title="Running Evals" icon="chart-bar" href="/sdk/concepts/running-evals">
    Statistical evaluations
  </Card>

  <Card title="API Reference" icon="book" href="/sdk/reference/mcp-client-manager">
    Complete API docs
  </Card>
</CardGroup>