Notion MCP Server

Instructions

Implementation Reference

• src/openapi-mcp-server/mcp/proxy.ts:56-120 (registration)

  Registers the MCP handlers for listing tools (which includes generating the tool list with names like 'API-{operationId}', e.g., 'API-retrieve-a-page-property') and calling tools. This is where all tools, including the target one, are registered.

  private setupHandlers() {
    // Handle tool listing
    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 }
    })
  
    // Handle tool calling
    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:78-119 (handler)

  The core handler function that executes any called MCP tool by mapping the tool name (e.g., 'API-retrieve-a-page-property') to the corresponding OpenAPI operation and proxying the HTTP request via HttpClient.

  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/openapi/parser.ts:166-197 (schema)

  Generates MCP tool schemas and names from OpenAPI spec. Tool names are constructed as 'API-{operationId}' (truncated if needed), input schemas from operation parameters and requestBody. Called during proxy initialization to define all tools including 'API-retrieve-a-page-property'.

  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)

  In the MCPProxy constructor, converts the Notion OpenAPI spec to MCP tools using OpenAPIToMCPConverter, storing the tool definitions and lookup for name-to-operation mapping.

    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:122-124 (helper)

  Helper to resolve tool name (operationId like 'API-retrieve-a-page-property') to the OpenAPI operation details (method, path, etc.).

  private findOperation(operationId: string): (OpenAPIV3.OperationObject & { method: string; path: string }) | null {
    return this.openApiLookup[operationId] ?? null
  }