Civo MCP Server

Instructions

Implementation Reference

• src/api/instances.ts:9-41 (handler)

  The core handler function that executes the tool logic by making a POST request to the Civo API to create a new instance.

  export async function createInstance(params: {
    hostname: string;
    size: string;
    template_id: string;
    count?: number;
    region?: string;
  }): Promise<CivoInstance> {
    checkRateLimit();
  
    const url = `${CIVO_API_URL}/instances`;
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${CIVO_API_KEY}`,
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        hostname: params.hostname,
        size: params.size,
        template_id: params.template_id,
        count: params.count?.toString() || '1',
        region: params.region || 'LON1',
      }),
    });
  
    if (!response.ok) {
      throw new Error(
        `Civo API error: ${response.status} ${response.statusText}`
      );
    }
  
    return response.json();
  }

• src/tools/instances.ts:3-34 (schema)

  Defines the tool metadata, name, description, and input schema for validation.

  export const CREATE_INSTANCE_TOOL: Tool = {
    name: 'create_instance',
    description: 'Create a new cloud instance on Civo',
    inputSchema: {
      type: 'object',
      properties: {
        hostname: {
          type: 'string',
          description: 'Fully qualified domain name',
        },
        size: {
          type: 'string',
          description: 'Instance size (e.g. g2.small)',
        },
        template_id: {
          type: 'string',
          description: 'Disk image ID',
        },
        count: {
          type: 'number',
          description: 'Number of instances to create',
          default: 1,
        },
        region: {
          type: 'string',
          description: 'Region identifier',
          default: 'LON1',
        },
      },
      required: ['hostname', 'size', 'template_id'],
    },
  };

• src/index.ts:71-71 (registration)

  Registers the 'create_instance' tool schema in the MCP server's capabilities.tools object.

  [CREATE_INSTANCE_TOOL.name]: CREATE_INSTANCE_TOOL,

• src/index.ts:129-156 (handler)

  The dispatch handler in the main CallToolRequestSchema that validates arguments and calls the createInstance function, returning the response.

  case 'create_instance': {
    if (
      typeof args !== 'object' ||
      args === null ||
      typeof args.hostname !== 'string' ||
      typeof args.size !== 'string' ||
      typeof args.template_id !== 'string'
    ) {
      throw new Error('Invalid arguments for create_instance');
    }
  
    const instance = await createInstance({
      hostname: args.hostname as string,
      size: args.size as string,
      template_id: args.template_id as string,
      count: args.count as number | undefined,
      region: args.region as string | undefined,
    });
    return {
      content: [
        {
          type: 'text',
          text: `Created instance ${instance.hostname} (ID: ${instance.id})`,
        },
      ],
      isError: false,
    };
  }