API-get-block-children

Retrieve child blocks from a Notion page or block to access nested content and structure within your Notion workspace.

Instructions

Retrieve block children

Input Schema

TableJSON Schema

Name	Required	Description
`block_id`	Yes	Identifier for a [block](ref:block)
`start_cursor`	No	If supplied, this endpoint will return a page of results starting after the cursor provided. If not supplied, this endpoint will return the first page of results.
`page_size`	No	The number of items from the full list desired in the response. Maximum: 100

Implementation Reference

src/openapi-mcp-server/mcp/proxy.ts:997-1098 (handler)

Core implementation of the API-get-block-children tool. Fetches the first page of block children, then parallelizes subsequent paginated pages (using next_cursor) in batches of 5, merges all results into a single complete response without has_more.

private async handleBlockChildrenParallel(
  operation: OpenAPIV3.OperationObject & { method: string; path: string }, 
  params: any,
  options?: RecursiveExplorationOptions
) {
  if (options?.runInBackground) {
    console.log(`Starting Notion API parallel processing: ${operation.method.toUpperCase()} ${operation.path}`);
  }
  
  // Get first page
  const initialResponse = await this.httpClient.executeOperation(operation, params);
  
  if (initialResponse.status !== 200) {
    if (options?.runInBackground) {
      console.error('Response error:', initialResponse.data);
    }
    return {
      content: [{ type: 'text', text: JSON.stringify(initialResponse.data) }],
    };
  }
  
  const results = initialResponse.data.results || [];
  let nextCursor = initialResponse.data.next_cursor;
  
  // Array for parallel processing
  const pageRequests = [];
  const maxParallelRequests = 5; // Limit simultaneous requests
  
  if (options?.runInBackground) {
    console.log(`Retrieved ${results.length} blocks from first page`);
  }
  
  // Request subsequent pages in parallel if available
  while (nextCursor) {
    // Clone parameters for next page
    const nextPageParams = { ...params, start_cursor: nextCursor };
    
    // Add page request
    pageRequests.push(
      this.httpClient.executeOperation(operation, nextPageParams)
        .then(response => {
          if (response.status === 200) {
            if (options?.runInBackground) {
              console.log(`Retrieved ${response.data.results?.length || 0} blocks from additional page`);
            }
            return {
              results: response.data.results || [],
              next_cursor: response.data.next_cursor
            };
          }
          return { results: [], next_cursor: null };
        })
        .catch(error => {
          if (options?.runInBackground) {
            console.error('Error retrieving page:', error);
          }
          return { results: [], next_cursor: null };
        })
    );
    
    // Execute parallel requests when batch size reached or no more pages
    if (pageRequests.length >= maxParallelRequests || !nextCursor) {
      if (options?.runInBackground) {
        console.log(`Processing ${pageRequests.length} pages in parallel...`);
      }
      const pageResponses = await Promise.all(pageRequests);
      
      // Merge results
      for (const response of pageResponses) {
        results.push(...response.results);
        // Set next cursor for next batch
        if (response.next_cursor) {
          nextCursor = response.next_cursor;
        } else {
          nextCursor = null;
        }
      }
      
      // Reset request array
      pageRequests.length = 0;
    }
    
    // Exit loop if no more pages
    if (!nextCursor) break;
  }
  
  if (options?.runInBackground) {
    console.log(`Retrieved ${results.length} blocks in total`);
  }
  
  // Return merged response
  const mergedResponse = {
    ...initialResponse.data,
    results,
    has_more: false,
    next_cursor: null
  };
  
  return {
    content: [{ type: 'text', text: JSON.stringify(mergedResponse) }],
  };
}

src/openapi-mcp-server/mcp/proxy.ts:246-254 (handler)

Dispatch in the main CallToolRequestSchema handler that specifically routes 'API-get-block-children' calls to the custom parallel handler instead of direct HTTP execution.

// Optimized parallel processing for API-get-block-children
if (name === 'API-get-block-children') {
  // Create basic options for logging control
  const blockOptions: RecursiveExplorationOptions = {
    runInBackground: false, // Default to not showing logs for regular API calls
  };
  
  return await this.handleBlockChildrenParallel(operation, params, blockOptions);
}

src/openapi-mcp-server/mcp/proxy.ts:115-126 (registration)

Generic registration of all converted OpenAPI operations as MCP tools in the ListToolsRequestSchema handler, including 'API-get-block-children'.

Object.entries(this.tools).forEach(([toolName, def]) => {
  def.methods.forEach(method => {
    const toolNameWithMethod = `${toolName}-${method.name}`;
    const truncatedToolName = this.truncateToolName(toolNameWithMethod);
    tools.push({
      name: truncatedToolName,
      description: method.description,
      inputSchema: method.inputSchema as Tool['inputSchema'],
    })
    console.log(`- ${truncatedToolName}: ${method.description}`)
  })
})

src/openapi-mcp-server/mcp/proxy.ts:98-101 (registration)
Initializes the tools registry and operation lookup (including API-get-block-children) by converting the OpenAPI specification using OpenAPIToMCPConverter.
```
const converter = new OpenAPIToMCPConverter(openApiSpec)
const { tools, openApiLookup } = converter.convertToMCPTools()
this.tools = tools
this.openApiLookup = openApiLookup
```

Notion ReadOnly MCP Server