Automate with Tools

Create tools, group them in toolsets, and read your MCP config with @protoboxai/sdk

Tools are functions your AI clients call over MCP — API lookups, data transforms, code. Define them once with @protoboxai/sdk and every connected MCP client can use them.

Installation

npm install @protoboxai/sdk

Setup

import { ProtoboxSDK } from '@protoboxai/sdk';

const client = new ProtoboxSDK({
  baseUrl: 'https://platform.protobox.ai',
  apiKey: process.env.PROTOBOX_API_KEY,
});

Methods return an ApiResponse<T> — check res.success and read res.data.

Create a tool

A tool has a name, description, type, an inputSchema (JSON Schema), and a type-specific configuration.

const res = await client.tools.create({
  name: 'lookup_order',
  description: 'Look up order details by order ID',
  type: 'http',
  inputSchema: {
    type: 'object',
    properties: {
      order_id: { type: 'string', description: 'The order ID (e.g. ORDER-12345)' },
    },
    required: ['order_id'],
  },
  configuration: {
    http: {
      method: 'GET',
      url: 'https://api.yourstore.com/orders/{{order_id}}',
      headers: { Authorization: 'Bearer {{secret:store_api_key}}' },
    },
  },
  isEnabled: true,
  tags: ['orders'],
});

const tool = res.data!;
console.log('Created tool:', tool.id);

CreateToolInput fields:

Field	Type	Required	Description
`name`	`string`	Yes	MCP tool name (snake_case recommended)
`description`	`string`	Yes	What the tool does (shown to the model)
`type`	`'http' \| 'javascript' \| 'code'`	Yes	Execution type
`inputSchema`	`object`	Yes	JSON Schema for inputs
`configuration`	`object`	Yes	Type-specific config (`http`, `javascript`, or `code`)
`isEnabled`	`boolean`	No	Available over MCP when enabled (default: true)
`tags`	`string[]`	No	Category tags

Test a tool

Execute a tool directly to verify it before connecting clients.

const res = await client.tools.execute(tool.id, { order_id: 'ORDER-12345' });

const result = res.data!;
console.log('Success:', result.success);
console.log('Output:', result.data);
console.log('Latency:', result.latencyMs, 'ms');

Use client.tools.test(id, args) for a dry-run execution that doesn't count against history.

Group tools into toolsets

A toolset is a curated collection of tools mapped to a scoped MCP endpoint.

const res = await client.toolsets.create({
  name: 'Support Tools',
  description: 'Tools for customer support clients',
  tools: [lookupOrder.id, processRefund.id],
});

const toolset = res.data!;
console.log('Created toolset:', toolset.id);

Manage toolset membership

// Add or remove tools
await client.toolsets.manageTools(toolset.id, { add: ['tool_new'] });
await client.toolsets.manageTools(toolset.id, { remove: ['tool_old'] });

// Override a tool's name/description within this toolset
await client.toolsets.setOverrides(toolset.id, {
  tool_new: { name: 'find_order', description: 'Find an order by ID' },
});

// Enable / disable the whole toolset
await client.toolsets.enable(toolset.id);
await client.toolsets.disable(toolset.id);

Read your MCP configuration

The mcp module returns your workspace's MCP server URL, status, and ready-to-paste client configs.

const res = await client.mcp.getConfig();
const config = res.data!;

console.log('MCP Server URL:', config.serverUrl);
console.log('Tools:', config.toolCount, 'Resources:', config.resourceCount);

// Ready-to-use client config blocks
console.log(config.agentConfigs.claude);
console.log(config.agentConfigs.cursor);

Check server health

const res = await client.mcp.getStatus();
const status = res.data!;
console.log('Healthy:', status.healthy, `${status.responseTimeMs}ms`);

List and call MCP tools

// List the tools exposed for an agent over MCP
const list = await client.mcp.listTools('agent_123');
console.log(list.data!.tools.map((t) => t.name));

// Call a tool by name
const call = await client.mcp.callTool('agent_123', 'lookup_order', {
  order_id: 'ORDER-12345',
});
console.log(call.data!.content);

Manage tools

// List with filters
const res = await client.tools.list({ type: 'http', isEnabled: true });
console.log(res.data!.tools);

// Enable / disable (controls MCP visibility)
await client.tools.enable('tool_abc123');
await client.tools.disable('tool_abc123');

// Execution history
const execs = await client.tools.getExecutions('tool_abc123', { status: 'failed' });

// Category (tag) breakdown
const cats = await client.tools.getCategories();

// Update / delete
await client.tools.update('tool_abc123', { description: 'Updated' });
await client.tools.delete('tool_abc123');

Full example

import { ProtoboxSDK } from '@protoboxai/sdk';

const client = new ProtoboxSDK({
  baseUrl: 'https://platform.protobox.ai',
  apiKey: process.env.PROTOBOX_API_KEY,
});

async function setupSupportTools() {
  const lookupOrder = (await client.tools.create({
    name: 'lookup_order',
    description: 'Look up order details by order ID',
    type: 'http',
    inputSchema: {
      type: 'object',
      properties: { order_id: { type: 'string' } },
      required: ['order_id'],
    },
    configuration: {
      http: { method: 'GET', url: process.env.API_URL + '/orders/{{order_id}}' },
    },
  })).data!;

  const toolset = (await client.toolsets.create({
    name: 'Support Tools',
    description: 'Core support tools',
    tools: [lookupOrder.id],
  })).data!;

  console.log('Toolset:', toolset.id, 'with', toolset.toolCount, 'tools');
  return toolset;
}

Types

import type {
  Tool,
  CreateToolInput,
  UpdateToolInput,
  ToolExecution,
  ExecuteResult,
  Toolset,
  CreateToolsetInput,
  McpConfigResponse,
  McpStatusResponse,
  McpTool,
} from '@protoboxai/sdk';