Custom Agent / SDK Quick Start

Prerequisites

• Node.js 18+ (for the ToolPilot MCP server and TypeScript SDK)
• TypeScript: npm install @modelcontextprotocol/sdk
• Python: pip install mcp

Step 1: Connect to ToolPilot

Use the MCP SDK to spin up the ToolPilot server and connect via stdio transport:

import { Client } from '@modelcontextprotocol/sdk/client';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio';

// Start the ToolPilot MCP server via stdio
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@anthropic/toolpilot-mcp'],
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

// Search for tools
const result = await client.callTool('search_tools', {
  query: 'vector database for embeddings',
});

console.log(result);

Step 2: Search for Tools

Call search_tools with a natural-language query. ToolPilot may return clarification questions — answer them with search_tools_respond to refine results.

1// Handle clarification if needed
2const searchResult = await client.callTool('search_tools', {
3  query: 'lightweight container orchestration for small teams',
4});
5
6// If result contains a clarification question:
7const refined = await client.callTool('search_tools_respond', {
8  session_id: searchResult.session_id,
9  answer: 'We need something simpler than Kubernetes, max 10 nodes',
10});

Step 3: Explore Available MCP Tools

ToolPilot exposes 5 MCP tools for different stages of tool discovery:

See the MCP Tools Reference for complete parameter documentation and response schemas.

Step 4: Report Outcomes

Close the feedback loop by reporting which tools worked:

await client.callTool('report_outcome', {
  tool: 'k3s',
  outcome: 'adopted',
  context: 'Perfect for our small cluster, easy setup',
});

Next Steps

• Full MCP Tools Reference →
• Understand the 4-stage search pipeline →
• Skip clarification with rich context →
• System architecture overview →