list_instances
Retrieve a list of all cloud instances on the Civo platform, with options to filter by region and paginate results for efficient management.
Instructions
List all instances on Civo
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination page | |
| per_page | No | Results per page | |
| region | No | Filter by region |
Implementation Reference
- src/index.ts:158-176 (handler)MCP server handler for the 'list_instances' tool call, which invokes the listInstances API function, formats the instances list into a string, and returns it as text content.case 'list_instances': { const instances = await listInstances(args); const instanceList = instances.items .map( i => `${i.hostname} (${i.id}) - ${i.status} - Public IP: ${i.public_ip || 'None'}` ) .join('\n'); return { content: [ { type: 'text', text: `Instances:\n${instanceList}`, }, ], isError: false, }; }
- src/tools/instances.ts:36-58 (schema)Defines the Tool object for 'list_instances' including name, description, and input schema for parameters like region, page, and per_page.export const LIST_INSTANCES_TOOL: Tool = { name: 'list_instances', description: 'List all instances on Civo', inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'Filter by region', }, page: { type: 'number', description: 'Pagination page', default: 1, }, per_page: { type: 'number', description: 'Results per page', default: 20, }, }, }, };
- src/index.ts:72-72 (registration)Registers the LIST_INSTANCES_TOOL in the server's capabilities.tools map by name.[LIST_INSTANCES_TOOL.name]: LIST_INSTANCES_TOOL,
- src/api/instances.ts:43-69 (helper)Helper function that makes the HTTP GET request to Civo API to retrieve the list of instances based on provided parameters.export async function listInstances(params: { region?: string; page?: number; per_page?: number; }): Promise<CivoInstanceList> { checkRateLimit(); const url = new URL(`${CIVO_API_URL}/instances`); if (params.region) url.searchParams.set('region', params.region); if (params.page) url.searchParams.set('page', params.page.toString()); if (params.per_page) url.searchParams.set('per_page', params.per_page.toString()); const response = await fetch(url.toString(), { headers: { Authorization: `Bearer ${CIVO_API_KEY}`, }, }); if (!response.ok) { throw new Error( `Civo API error: ${response.status} ${response.statusText}` ); } return response.json(); }