Build an Agent CLI over MCP (TypeScript)

mkdir swarms-agent-cli && cd swarms-agent-cli
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D tsx typescript

{
  "name": "swarms-agent-cli",
  "type": "module",
  "scripts": {
    "start": "tsx agent.ts"
  }
}

export SWARMS_API_KEY="your-api-key-here"

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const SERVER_URL = "https://mcp.swarms.world/mcp";

export async function connect(): Promise<Client> {
  const apiKey = process.env.SWARMS_API_KEY;
  if (!apiKey) {
    throw new Error("SWARMS_API_KEY is not set");
  }

  // The credential rides on the transport as a header. It is never a tool
  // argument, so the model driving these tools never sees it.
  const transport = new StreamableHTTPClientTransport(new URL(SERVER_URL), {
    requestInit: { headers: { "x-api-key": apiKey } },
  });

  const client = new Client({ name: "swarms-agent-cli", version: "1.0.0" });
  await client.connect(transport);
  return client;
}

import { connect } from "./client.js";

const client = await connect();
const { tools } = await client.listTools();

console.log(`${tools.length} tools available:\n`);
for (const tool of tools) {
  console.log(`  ${tool.name}`);
}

await client.close();

npx tsx list.ts

import { connect } from "./client.js";

const client = await connect();

const result = await client.callTool({
  name: "run_agent_v1_agent_completions_post",
  arguments: {
    agent_config: {
      agent_name: "explainer",
      description: "Explains technical concepts concisely and correctly.",
      system_prompt:
        "You are a precise technical explainer. Prefer short paragraphs " +
        "and concrete examples over abstractions. Never pad your answer.",
      model_name: "gpt-4o-mini",
      max_loops: 1,
      max_tokens: 2000,
    },
    task: "Explain the CAP theorem in three bullets.",
  },
});

console.log(result.structuredContent);
await client.close();

npx tsx agent.ts

if (result.isError) {
  // content[0].text holds the upstream status line and body.
  throw new Error(`Swarms call failed: ${result.content[0].text}`);
}

const payload = result.structuredContent as any;
console.log(payload.outputs[0].content);
console.log(`cost: $${payload.usage.total_cost}`);

{
  "job_id": "agent-b0abf28…",
  "success": true,
  "name": "explainer",
  "outputs": [
    { "role": "explainer", "content": "…", "timestamp": "…", "message_id": "…" }
  ],
  "usage": {
    "input_tokens": 7,
    "output_tokens": 62,
    "total_tokens": 69,
    "total_cost": 0.001192
  }
}

type Turn = { role: string; content: string };

async function ask(
  client: Client,
  task: string,
  history: Turn[],
): Promise<{ answer: string; cost: number }> {
  const result = await client.callTool({
    name: "run_agent_v1_agent_completions_post",
    arguments: {
      agent_config: {
        agent_name: "explainer",
        system_prompt: "You are a precise technical explainer.",
        model_name: "gpt-4o-mini",
        max_loops: 1,
        max_tokens: 2000,
      },
      task,
      // Omit history entirely on the first turn rather than sending [].
      ...(history.length > 0 ? { history } : {}),
    },
  });

  if (result.isError) {
    throw new Error(`Swarms call failed: ${result.content[0].text}`);
  }

  const payload = result.structuredContent as any;
  const answer = payload.outputs[payload.outputs.length - 1].content;
  return { answer, cost: payload.usage.total_cost };
}

const history: Turn[] = [];

for (const question of ["What is the CAP theorem?", "Which do most SQL databases pick?"]) {
  const { answer } = await ask(client, question, history);
  console.log(`\nQ: ${question}\nA: ${answer}`);

  history.push({ role: "user", content: question });
  history.push({ role: "assistant", content: answer });
}

const result = await client.callTool(
  { name: "run_agent_v1_agent_completions_post", arguments: { /* … */ } },
  undefined,
  { timeout: 300_000 }, // 5 minutes
);

import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { connect } from "./client.js";

type Turn = { role: string; content: string };

const AGENT_CONFIG = {
  agent_name: "explainer",
  description: "Explains technical concepts concisely and correctly.",
  system_prompt:
    "You are a precise technical explainer. Prefer short paragraphs and " +
    "concrete examples over abstractions. Never pad your answer.",
  model_name: "gpt-4o-mini",
  max_loops: 1,
  max_tokens: 2000,
};

async function ask(client: Client, task: string, history: Turn[]) {
  const result = await client.callTool(
    {
      name: "run_agent_v1_agent_completions_post",
      arguments: {
        agent_config: AGENT_CONFIG,
        task,
        ...(history.length > 0 ? { history } : {}),
      },
    },
    undefined,
    { timeout: 300_000 },
  );

  if (result.isError) {
    throw new Error(`Swarms call failed: ${(result.content as any)[0].text}`);
  }

  const payload = result.structuredContent as any;
  return {
    answer: payload.outputs[payload.outputs.length - 1].content as string,
    cost: payload.usage.total_cost as number,
  };
}

const question = process.argv.slice(2).join(" ");
if (!question) {
  console.error('usage: npm start "your question"');
  process.exit(1);
}

const client = await connect();
let spent = 0;

try {
  const first = await ask(client, question, []);
  console.log(first.answer);
  spent += first.cost;

  const history: Turn[] = [
    { role: "user", content: question },
    { role: "assistant", content: first.answer },
  ];

  const followUp = "In one sentence, what is the most common mistake people make about this?";
  const second = await ask(client, followUp, history);
  console.log(`\n--- ${followUp} ---\n${second.answer}`);
  spent += second.cost;
} finally {
  console.log(`\ntotal cost: $${spent.toFixed(6)}`);
  await client.close();
}

npm start "Explain the CAP theorem in three bullets."