API-patch-block-children

Append child content to a Notion block or page using the Notion MCP Server. Specify block ID and array of child blocks to add content after an existing block, enhancing workspace organization.

Instructions

Notion | Append block children

Input Schema

TableJSON Schema

Name	Required	Description
`after`	No	The ID of the existing block that the new block should be appended after.
`block_id`	Yes	Identifier for a [block](ref:block). Also accepts a [page](ref:page) ID.
`children`	Yes	Child content to append to a container block as an array of [block objects](ref:block)

Implementation Reference

src/openapi-mcp-server/mcp/proxy.ts:78-119 (handler)

Generic MCP tool execution handler for all tools derived from OpenAPI spec, including "API-patch-block-children". It resolves the tool name to the corresponding OpenAPI operation (PATCH /v1/blocks/{block_id}/children), executes the HTTP request via HttpClient, and formats the response as MCP content.

this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: params } = request.params

  // Find the operation in OpenAPI spec
  const operation = this.findOperation(name)
  if (!operation) {
    throw new Error(`Method ${name} not found`)
  }

  try {
    // Execute the operation
    const response = await this.httpClient.executeOperation(operation, params)

    // Convert response to MCP format
    return {
      content: [
        {
          type: 'text', // currently this is the only type that seems to be used by mcp server
          text: JSON.stringify(response.data), // TODO: pass through the http status code text?
        },
      ],
    }
  } catch (error) {
    console.error('Error in tool call', error)
    if (error instanceof HttpClientError) {
      console.error('HttpClientError encountered, returning structured error', error)
      const data = error.data?.response?.data ?? error.data ?? {}
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              status: 'error', // TODO: get this from http status code?
              ...(typeof data === 'object' ? data : { data: data }),
            }),
          },
        ],
      }
    }
    throw error
  }
})

src/openapi-mcp-server/mcp/proxy.ts:58-75 (registration)

MCP tool listing handler that registers all OpenAPI-derived tools, constructing names like "API-patch-block-children" from 'API' + operationId 'patch-block-children', including description and inputSchema.

this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  const tools: Tool[] = []

  // Add methods as separate tools to match the MCP format
  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'],
      })
    })
  })

  return { tools }
})

src/openapi-mcp-server/openapi/parser.ts:166-197 (schema)

Generates MCP tool definitions (name, description, inputSchema) from OpenAPI operations, creating the "API-patch-block-children" tool from Notion's patchBlockChildren operation including schema for path param block_id and body.

convertToMCPTools(): {
  tools: Record<string, { methods: NewToolMethod[] }>
  openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }>
  zip: Record<string, { openApi: OpenAPIV3.OperationObject & { method: string; path: string }; mcp: NewToolMethod }>
} {
  const apiName = 'API'

  const openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }> = {}
  const tools: Record<string, { methods: NewToolMethod[] }> = {
    [apiName]: { methods: [] },
  }
  const zip: Record<string, { openApi: OpenAPIV3.OperationObject & { method: string; path: string }; mcp: NewToolMethod }> = {}
  for (const [path, pathItem] of Object.entries(this.openApiSpec.paths || {})) {
    if (!pathItem) continue

    for (const [method, operation] of Object.entries(pathItem)) {
      if (!this.isOperation(method, operation)) continue

      const mcpMethod = this.convertOperationToMCPMethod(operation, method, path)
      if (mcpMethod) {
        const uniqueName = this.ensureUniqueName(mcpMethod.name)
        mcpMethod.name = uniqueName
        mcpMethod.description = this.getDescription(operation.summary || operation.description || '')
        tools[apiName]!.methods.push(mcpMethod)
        openApiLookup[apiName + '-' + uniqueName] = { ...operation, method, path }
        zip[apiName + '-' + uniqueName] = { openApi: { ...operation, method, path }, mcp: mcpMethod }
      }
    }
  }

  return { tools, openApiLookup, zip }
}

src/openapi-mcp-server/mcp/proxy.ts:48-54 (registration)
Initializes the MCPProxy by converting Notion OpenAPI spec to internal tools map and openApiLookup (used for dispatching), including the entry for "API-patch-block-children".
```
  const converter = new OpenAPIToMCPConverter(openApiSpec)
  const { tools, openApiLookup } = converter.convertToMCPTools()
  this.tools = tools
  this.openApiLookup = openApiLookup

  this.setupHandlers()
}
```
src/openapi-mcp-server/mcp/proxy.ts:89-90 (helper)
Dispatches to HttpClient.executeOperation which performs the actual HTTP PATCH request for the tool.
```
const response = await this.httpClient.executeOperation(operation, params)
```

Notion MCP Server